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An Introduction 
to Starbase Graphics 



Graphics with C 

Welcome 

This manual is designed to teach you how to use some fundamental procedures that are 
included in the Starbase Graphics Library on your HP-UX system. These procedures 
can be accessed from the C, Fortran77 and Pascal programming languages available for 
your system. This subsection will present a progressive example using the C Program¬ 
ming Language. The following subsections cover the same material using the Fortran77 
Programming Language and the the Pascal programming language. 

This manual was written with the assumption that you are familiar with your HP-UX 
Operating System, including the appropriate programming languages, compilers, linkers, 
editors, etc. If this is not the case, the information you need is available in the extensive 
documentation provided with your system. 

This manual also assumes that you are familiar with basic computer graphics concepts. 
If this is not the case, there are many excellent books and courses available to provide 

__ „ 4 _: 

LJLiJLS 111JHJI illcttlUll. 


The example programs used in this tutorial are included with your system in the 
/usr/lib/starbase/demos directory. You are encouraged to compile and run these pro¬ 
grams as you read the manual. When you see how the programs work, modify them as 
you desire to see how each part contributes to the whole. Be aware that the example 
programs assume a system configuration which may differ from yours, and that the gopen 
procedure parameters and the device drivers linked to the program may need changing 
to match your system. 


An Introduction to Starbase Graphics 1 




NOTE 


Demonstration programs and routines in /usr/lib/starbase/demos 
are for the purpose of instruction only. They are not part of the 
HP-UX package, and as such, they are not covered by any war¬ 
ranty, expressed or implied. Hewlett Packard shall not be liable 
for incidental or consequential damages in connection with, or aris¬ 
ing out of, the furnished, performance, or use of these routines. 


Preparation 

The directions concerning the execution of the example programs presented in this man¬ 
ual assumes your current directory is /usr/lib/starbase/demos. To make this directory 
your current working directory, use the change directory (cd) command as follows: 

cd /usr/lib/starbase/demos 

A discussion of the hierarchial directory structure used by the HP-UX Operating System 
is found in the Systems Administrator manual supplied with your system. 

For further details on the cd command, use the man command. For example, 
man cd 

The man command prints the reference page for the specified command on the display. 

The example programs presented in this manual are included with your operating system. 
They are located in the /usr/lib/starbase/demos directory. The examples are provided 
as source code. To read the code, use the HP-UX more or cat commands. To modify the 
code, use an appropriate editor, such as the vi editor. 

To execute the example programs on other devices, they must be compiled and linked to 
the correct drivers. The shell script below will accomplish this for you. 
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Device Drivers 

The Starbase device drivers are located in the directory /usr/lib and have file names 
appropriate to access by the “-1” option of the c compiler (cc) command. 

Take a moment and list the device driver files in /usr/lib to see which device drivers are 
available with your system. All device driver file names begin with libdd prefix, followed 
by the device type. To list these files, type in: 

Is /usr/lib/libdd* 

As you can see, there are several drivers to choose from. 

The HP-GL device driver is (/usr/lib/libddhpgl .a) and the HP 262x device driver is 
(/usr/lib/libdd262x.a). These are the device drivers included in the example programs. 

For further details concerning the Starbase Device Drivers, read the appropriate sections 
in the Starbase Device Drivers Library manual. 

A Shell Script 

The following shell script was used to compile and execute the example programs dis¬ 
cussed in this manual. The script works with both the Bourne Shell and the C Shell (the 
C shell calls the Bourne shell automatically). 

The “-1” option was used to reduce typing. This compiler option prepends /usr/lib/lib 
to the filename and appends .a to the file name. Thus, 

... -lddhpgl 

is processed as if it were 

... /usr/lib/libddhpgl.a 

The HP-GL and HP 262x device drivers were linked in by the script. The sbl and sb2 
files are included to resolve all unresolved references generated by the Starbase programs. 

PR0G=$1 

shift 

cc -o $PR0G $PR0G.c $* -lddhpgl -ldd262x -lsbl -lsb2 
$PR0G 

This script is stored as an executable file under the file name CC in: 

/usr/lib/starbase/demos. 
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To compile and execute the example program exampleIc.c, enter the following: 

CC examplelc 

To execute the compiled program examplelc again, type in: 
examplelc 

If you want the same program executed on an HP-GL plotter, type in: 

examplelc /dev/hpgl hpgl 

To execute the example with other devices, you must link the correct devices to the 
program. 

To link the HP 98700 driver using this script, just type in: 

CC examplelc -ldd98700 

To execute the example after being linked with the HP 98700 device driver, just type in: 
examplelc /dev/hp98700 hp98700 
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The Data to be Plotted 

The following data is to be presented in graphical form. The example program to do this 
follows. 


Table 1-1. Test Data 


Test 

Value 

Test 

Value 

Test 

Value 

Test 

Value 

0 

0.1610 

1 

0.1625 

2 

0.1625 

3 

0.1628 

4 

0.1636 

5 

0.1631 

6 

0.1627 

7 

0.1608 

8 

0.1610 

9 

0.1606 

10 

0.1607 

11 

0.1617 

12 

0.1614 

13 

0.1626 

14 

0.1634 

15 

0.1640 

16 

0.1656 

17 

0.1660 

18 

0.1644 

19 

0.1651 

20 

0.1635 

21 

0.1641 

22 

0.1628 

23 

0.1619 

24 

0.1630 

25 

0.1624 

26 

0.1627 

27 

0.1644 

28 

0.1644 

29 

0.1657 

30 

0.1660 

31 

0.1670 

32 

0.1672 

33 

0.1666 

34 

0.1658 

35 

0.1662 

36 

0.1646 

37 

0.1633 

38 

0.1634 

39 

0.1636 

40 

0.1645 

41 

0.1652 

42 

0.1656 

43 

0.1677 

44 

0.1689 

45 

0.1680 

46 

0.1696 

47 

0.1680 

48 

0.1674 

49 

0.1677 

50 

0.1669 

51 

0.1655 

52 

0.1665 

53 

0.1662 

54 

0.1667 

55 

0.1668 

56 

0.1681 

57 

0.1688 

58 

0.1687 

59 

0.1707 

60 

0.1716 

61 

0.1716 

62 

0.1694 

63 

0.1698 

64 

0.1683 

65 

0.1683 

66 

0.1671 

67 

0.1681 

68 

0.1683 

69 

0.1684 

70 

0.1681 

71 

0.1698 

72 

0.1705 

73 

0.1723 

74 

0.1730 

75 

0.1734 

76 

0.1714 

77 

0.1722 

78 

0.1716 

79 

0.1696 

80 

0.1702 

81 

0.1699 

82 

0.1684 

83 

0.1706 

84 

0.1696 

85 

0.1715 

86 

0.1730 

87 

0.1737 

88 

0.1739 

89 

0.1751 

90 

0.1732 

91 

0.1747 

92 

0.1729 

93 

0.1717 

94 

0.1710 

95 

0.1707 

96 

0.1706 

97 

0.1709 

98 

0.1713 

99 

0.1720 
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The Data in Clist Format 

The first column shows the first few file entries as a clist without move/draw indicators. 
The second column shows the first few data entries as a clist with move(l)/draw(0) 
indicators. 

Table 1-2. Data in Clist Format 


Clist without 
Move/Draw Indicators 

Clist with 

Move/Draw Indicators 

0 

0 

0.1610 

0.1610 

1 

0 (a move indicator) 

0.1625 

1 

2 

0.1625 

0.1625 

1 (a draw indicator) 

3 

2 

0.1628 

0.1625 

4 

1 (another draw indicator) 

0.1636 

3 

5 

0.1628 

0.1631 

1 

6 

4 

0.1627 

0.1636 

7 

1 

0.1608 

5 

8 

0.1631 

0.1610 

1 

9 

6 

0.1606 

0.1627 

10 

1 

0.1607 

7 

11 

0.1608 

0.1617 

1 

12 

8 

0.1614 

0.1610 

13 

1 

0.1626 

9 

14 

0.1606 

0.1634 

1 

15 

10 

0.1640 

0.1607 

16 

1 

0.1656 

11 

17 

0.1617 

0.1660 

1 

18 

12 

0.1644 

0.1614 

19 

1 

0.1651 

13 
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The Results Desired 

The following picture shows the plot to be created by the example programs described 
in the subsection. 



Figure 1-1. The Results Desired 
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A Template C Program 

The following is a template program that will be filled with Starbase procedure and 
function calls to draw the example voltage plot. As listed, this program opens the 
specified device, clears the clipping area and then closes the device. The capability of 
executing the program on an HP262x Graphics Terminal or a specified device is included. 

For more information on C programming, read The C Programming Language by Brian 
W. Kernighan and Dennis M. Ritchie. This book is included with your HP-UX Manual 
Set. 

This program is stored as examplelc.c. 

#include <starbase.c.h> 

main(argc,argv) 

int argc; char *argv[] ; 

{ 

int fildes; 

if (argc > 2) fildes=gopen(argv[1],OUTDEV,argv[2],INIT); 
else fildes=gopen("/dev/tty",OUTDEV,"hp262x",INIT); 
if (fildes == -1) exit(-1); 

gclose(fildes); 

> 

The Include File 

The file starbase.c .h contains the definitions and terms needed for any Starbase program 
written in C. This file is located in the /usr/include directory. 

To see what definitions and terms are needed, use the more command. The syntax is: 

more /usr/include/starbase.c.h 
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The Gopen Function 

The function gopen opens the specified graphic device. This function requires four pa- 
rameters: 

1. Device File Name - Device files are created by the System Administrator. Device 
files are located in the /dev directory. In the following examples, the device file tty 
is used. 

2. Performance Mode - This parameter may be one of the following: 

• OUTDEV - device driver is to output information to the device. 

• INDEV - device driver is to read information from the device. 

• OUTINDEV - device driver can send and receive information to and from the 
device. 

The following examples use OUTDEV since the example program is to be drawn on the 
output device’s display. 

3. Character Representation of the Driver Type - For the following example, this 
will be hp262x. This parameter identifies the driver to be used. The hp262x driver 
interrogates the device specified by the device file name and tests to see if the device 
is an HP 2623 Graphics Terminal or an HP 2627 Culoi Graphics Terminal, and acts 
accordingly. 

A possible character representation for an HP-GL plotter is hpgl. 

4. Operation Mode - This parameter may be one of the following: 

0 - open the device, but do nothing else. 

INIT - open and initialize the device in a device dependent way. 

RESET - open and completely initialize the device. 

SPOOLED - open the device for spooled operation. Spooled output may be saved 
in a file for later display. 

THREE_D - open the device and set Starbase to 3-dimensional mode. 

These modes may be combined with the proper OR syntax. For C this is the 
vertical bar (|) as in (INIT|SPOOLED). 

By doing an OR operation on INIT and SPOOLED, the graphic device can be opened, 
initialized and spooled to a file. 
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For example: 

fildes = gopen("spoolfile”,OUTDEV,"hpgl",INITI SPOOLED); 

If the opening is not successful, gopen returns a value of -1. If the opening is successful, 
a positive integer (file descriptor) is returned and the HP-GL device is initialized and 
ready for spooled output. 

Further information can be obtained about this procedure by using the man command. 
Just type in: 

man 3 gopen 

The Gclose Function 

To properly close a graphics device, use the gclose function. The fildes file descriptor 
identified by the gopen function is used to identify a particular device for all following 
Starbase procedures and functions, including gclose. 

Further information can be obtained about this procedure by using the man command. 
Just type in: 

man 3 gclose 
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A Review 

As a review, the following table lists information about the files, functions and commands 
just discussed. 

Table 1-3. A Review 


Required Items 

Learn More 

The cd Command 

/ usr / man / man 1 /cd. 1 
(man cd) 

The cc Compiler Command 

/usr / man/man 1 /cc. 1 
(man cc) 

Shell Scripts 

HP-UX Concepts and Tutorials, 
volume 3. 

Device Drivers 

Starbase Device Drivers Library, 
/usr/lib/libdd* 

(Is /usr/lib/libdd...) 

C Programming 

The C Programming Language 
by Kernighan and Ritchie 

Definitions and Terms needed 
for any Starbase program in C. 

/usr/include/starbase.c.li 
(more /usr/include/starbase.c.h) 

gopen 

/usr/man/man3/gopen.3g 
(man 3 gopen) 

gclose 

/ usr / man / man3 / gclose. 3 g 
(man 3 gclose) 
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Virtual Device Coordinates 

The default Cartesian coordinate system used by the Starbase procedures is called the 
Virtual Device Coordinate (VDC) system. This system can be considered a 2-dimensional 
subset of the Cartesian plane with default x- and y-axis values ranging from 0.0 to 1.0. In 
3-dimensional graphics, this system can also be considered a subset of Cartesian 3-space 
with default x-, y- and z-axis values ranging from 0.0 to 1.0. Locations in VDC space 
are specified in VDC values as specified by the vdc_extent procedure. 

The procedure gopen automatically creates a Virtual Device Coordinate to Device Co¬ 
ordinate (DC) transformation matrix for each opened graphic device. All VDC data is 
processed through this matrix before being set to the target device. Since each device has 
a unique transformation matrix, the same data will appear as expected on each device. 

The range of values used for this system can be altered with the vdc_extent procedure. 

Use the push_vdc_matrix procedure to force the current working matrix to be the VDC 
to DC transformation matrix. 

Device Coordinates 

Device coordinate Space is the Cartesian 2-dimensional space that is the device’s output 
surface. The range and magnitude of x- and y-axis values is defined by each device. 

Device Coordinate procedures bypass the VDC to DC transformation matrix. Such pro¬ 
cedures begin with the characters dc , for “device coordinate”. For example, dedraw will 
draw a line on the specified device using the untransformed coordinate values specified. 

To transform VDC values to DC values, use the vdc_to_dc procedure. 
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World Coordinates 

World coordinates can have any value the user desires. This is handy when the data is 
to be used for purposes other than making a drawing. 

Since world coordinates can be of any value, they must be transformed to device co¬ 
ordinates before being drawn on a graphic device. This transformation can be done in 
several ways. For example: 

• A transformation matrix with the appropriate values to transform the World Co¬ 
ordinate data into Device Coordinate data may be supplied by the user. 

• A transformation matrix with the appropriate values to transform the World Coor¬ 
dinate data into Virtual Device Coordinate data may be supplied by the user. This 
matrix could then be concatenated (matrix multiplied) with the Virtual Device Co¬ 
ordinate to Device Coordinate transformation matrix to make a World Coordinate 
to Device Coordinate Matrix. 

For instance, in 2-dimensional mode, a matrix containing: 

cos 9 sin 0 

-sin 0 cos 0 

0 0 

will rotate world coordinates counter-clockwise by an angle of 6. 

• The Easiest Way is to use the vdc_extent procedure to change the ranges of values 
used to define the Virtual Device Coordinate Space so that the world coordinate 
values are now contained in VDC space. Any time the vdc_extent procedure is 
used, a new Virtual Device Coordinate to Device Coordinate matrix is calculated 
that maps Virtual Device Coordinate Space into Device Coordinate Space. 
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Setting the VDC Extent 

In the example problem, we want to plot voltage values against the associated measure¬ 
ment number. Our voltage data ranges from just over 0.1600 through just under 0.1800, 
while we have 100 measurements (from 1 to 100). 

Logical values for the vdc extent would be -20 to 105 on the x-axis and 0.1575 to 0.1825 
in the y-axis. This will allow us to plot the data in a rectangle of size 0-100 on the x-axis 
and 0.1600-0.1800 on the y-axis and still leave room for labels within the vdc extent and 
outside the plotting area. Since we are doing 2-dimensional graphics, the z-coordinates 
are both 0.0. The syntax to do this is: 

vdc.extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 

Detailed information on this procedure can be found using the HP-UX man command as 
follows: 

man 3 vdc_extent 


NOTE 

The decision was made to follow ANSI parameter patterns in the 
Starbase procedures. These parameter patterns are NOT CON¬ 
SISTENT. One procedure may call for xl,yl,zl,x2,y2,z2 while the 
next may require xl,x2,yl,y2,zl,z2. Hopefully this inconstancy will 
be removed from the ANSI standard and thus from the Starbase 
procedures. 
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Clipping 

Clipping is the process of not allowing selected graphic data to be displayed. There are 
two clipping processes: 

• Hard Clip - This is clipping done by the graphic output device that physically 
stops plotting outside the physical limits of the device’s display area. For example, 
a plotter’s pen can not draw past the physical edge of the plotter’s platen. 

• Soft Clip - This is clipping done by the graphics software to limit the visible portion 
of the plot. Soft clipping can be done to both 2-dimensional and 3-dimensional data. 

Starbase provides two clipping boundaries: 

• The Clip Rectangle - A rectangle can be specified with the clip.rectangle proce¬ 
dure that defines subsequent clipping boundaries. 

• The VDC Extent - The rectangle defined by the vdc_extent procedure can also be 
used to define subsequent clipping boundaries. 

The clip.indicator procedure identifies which of the two boundaries to clip to. 

The clip_depth procedure is used to define the front and back clipping planes for 
3-dimensional graphics. Front and back clipping is enabled or disabled with the 
depth_indicator procedure. 
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Isotropic (undistorted) Mapping 

Isotropic mapping is when one unit in the x-axis exactly equals one unit in the y-axis. 
This is sometimes referred to as undistorted plotting. 

The mapping.mode procedure sets the mapping mode to either anisotropic or isotropic 
plotting mode. The default is isotropic. 

The following example program draws an isotropic square around the default Virtual 
Device Coordinate space. This program is in file example2c.c. 

#include <starbase.c.h> 

main(argc,argv) 

int argc; char *argv[]; 

{ 

int fildes; 

if (argc > 2) fildes=gopen(argv[1],OUTDEV,argv[2],INIT); 
else fildes=gopen("/dev/tty".OUTDEV,"hp262x",INIT); 
if (fildes == -1) exit(-l); 

interior_style(fildes,INT_HQLLOW,TRUE); 
rectangle(fildes,0.0,0.0,1.0,1.0); 

gclose(fildes); 

> 
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Anisotropic (distorted) Mapping 

Anisotropic mapping where one unit in the X direction does not have to equal one unit 
in the Y direction. This is sometimes called distorted plotting. 

The mapping.mode procedure sets the mapping mode to either anisotropic or isotropic 
plotting mode. The following single line was added to the preceeding isotropic program 
and the anisotropic results are shown in Figure 1-3. The rectangle still frames the VDC 
default space, but now the space fills the usable portion of the display. This program is 
in exampleSc.c . 

mapping_mode(fiIdes.TRUE); 



Figure 1-3. An Anisotropic Frame of VDC Space 


Since the scale for the voltage measurements is not the same as the scale for the number 
of measurements, anisotropic plotting is appropriate. 
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Viewports 

The viewport is the portion of the output display that is used to draw the picture. This 
can be all or only a part of the display. 

The viewport boundaries is defined by several procedures. 

• set_pl_p2 - This procedure defines the physical region that contains the viewport. 

• mapping_mode - This procedure defines the viewport as isotropic (distorted) or 
anisotropic (undistorted). If anisotropic, the viewport is the same as the rect¬ 
angle defined by the set_pl_p2 procedure. If the viewport is isotropic, the viewport 
is the largest rectangle with the same aspect ratio as the VDC extent that will 
fit in the rectangle defined by the set_pl_p2 procedure and is positioned in that 
rectangle by the viewport.justification procedure. 

• viewport.justification - This procedure defines the fraction of “white space” (the 
area of the set_pl_p2 rectangle not within the viewport) to the left or bottom of 
the viewport. The default is .5 (50%), so the viewport is centered in the rectangle 
defined by set_pl_p2. This procedure only applies to isotropic viewports. 


An Introduction to Starbase Graphics 19 



Rectangles 

The rectangle procedure provides an easy way to draw rectangles. All you need to 
specify is the device needing a rectangle and the coordinates of two opposite comers of 
the rectangle. A default rectangle has a filled interior and no perimeter. 

To see the extent of the Virtual Device Coordinate Space and to draw a frame around 
the location on the display, two rectangles are drawn. The syntax for these rectangles is: 

rectangle(fildes,-20,0.1575,105.0,0.1825); 
rectangle(fildes,0,0.1600,100.0,0.1800); 

To make rectangles hollow, and add the perimeter, use the interior_style procedure. 
The following syntax will do the job. 

interior_style(ftides,INT_H0LL0W,TRUE); 

The following program segment is added to the program in order to draw the rectangles. 
The program is stored as example4 c.c. 

vdc_extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 
clip_rectangle(ftides,-20.0,105.0,0.1575,0.1825); 
mapping_mode(ftides,TRUE); 

interior_style(fildes,INT_H0LL0W,TRUE); 
rectangle(f tides,-20.0,0.1575,105.0,0.1825); 
rectangle(ftides,0.0,0.1600,100.0,0.1800); 
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Figure 1-4. Two Rectangles 
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Plotting the Data 

The following program will read the plot data from the file data and draw the results 
in Virtual Device Coordinate space. The main procedure is polyline which will move 
the graphics pen to the first (X,Y) data location and then draw to the remaining data 
locations. The data is read into a single-dimension array usable by polyline. The number 
of points to be drawn to is i/2 and the FALSE flag indicates that there are no move-draw 
(0 for move, 1 for draw) indicators in the data. 

You need to include <stdio.h> to access the file data. The syntax is: 

#include <stdio.h> 


fp = fopenC'data", "r"); 

while(i<200 && f scanf (fp, " # / 0 f" ,&coords [i] ,fecoords [i+1]) != EOF) 
i+=2; 

fclose(fp); 

polyline2d(fildes,coords,i/2.FALSE); 

The results of this modification to the example program are shown in Figure 1-5. This 
drawing was made with example5c.c. 
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Figure 1-5. Plotted Data Only 
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Labels 

Let us now label the drawing. We will use two fonts, different character paths, and 
different text alignments to show some of the capabilities of the system. 

The syntax to do this is: 

text.alignment(fildes,TA_CENTER,TA_T0P,0.0,0.0); 
character_height(fildes,0.001); 

text2d(fildes,50.0,0.1588,"Time (seconds)",VDC.TEXT,FALSE); 
text.path(fildes,PATH_D0WN); 

text.alignment(fildes,TA_CENTER,TA.HALF,0.0,0.0); 
text2d(fildes,-14.0,0.1700,"Voltage",VDC.TEXT,FALSE); 

text_font_index(fildes,2); 

character_path(fildes,PATH_RIGHT); 

text.alignment(fildes,TA.CENTER,TA.BOTTOM,0.0,0.0); 

text2d(fildes,50.0,0.1810,"VOLTAGE VARIANCE",VDC.TEXT,FALSE); 

Our example is now shown in Figure 1-6. This program is stored in example6c.c. 
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Figure 1-6. A Labeled Plot 
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Tic Marks 

We now need to add the numerated tic marks. This is done with two loops. We use 
sprintf to change the tic mark numbers into strings to be drawn as text. 

text_alignment(fildes,TA_CENTER,TA.CONTINUOUS.VERTICAL,0.0,1.2); 
character_height(fildes,0.0006); 

x = 0.0; 

sprintf(number, "°/,d", (int)x) ; 

text2d(fildes,x,0.1598,number,VDC.TEXT,FALSE); 
for (i=10; i--;) { 

for (j =5; j—;) l 

move2d(fildes,x,0.1600); 
draw2d(fildes,x,0.1603); 
x += 2.0; 

> 

move2d(fildes,x,0.1600); 
draw2d(fildes,x,0.1605); 
sprintf (number, " # /,d" , (int)x) ; 

text2d(fildes,x,0.1600,number,VDC.TEXT,FALSE); 

> 

text_alignment(fildes,TA_C0NTINU0US_H0RIZ0NTAL,TA.HALF,1.2,0.0); 
y = 0.1600; 

sprintf (number, ,,# /«5.4f M , y) ; 
text2d(fildes,0.0,y,number,VDC.TEXT,FALSE); 
for (i=8; i--;) { 

for (j=5; j--;) { 

move2d(fildes,0.0,y); 
draw2d(fildes,1.0,y); 
y += 0.0005; 

> 

move2d(fildes,0.0,y); 

draw2d(fildes,2.0,y); 

sprintf (number, <,0 /«5.4f M , y) ; 

text2d(fildes,0.0,y,number,VDC.TEXT,FALSE); 

> 

With the tic marks, we have the final picture. 
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The Final Picture 
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The whole program 

#include <stdio.h> 

#include <starbase.c.h> 

main(argc,argv) 

int argc; char *argv[] ; 

int fildes; 
int i=0, j=0; 
float x, y; 
float coords[200]; 

FILE *fp; 
char number[80]; 

if (argc > 2) fildes=gopen(argv[1],OUTDEV,argv[2],INIT); 
else fildes=gopen("/dev/tty".OUTDEV,"hp262x",INIT); 
if (fildes == -1) exit(-l); 

vdc.extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 
clip.rectangle(fildes,-20.0,105.0,0.1575,0.1825); 
mapping_mode(fildes.TRUE); 

interior.style(fildes,INT.HOLLQW,TRUE); 
rectangle(fildes,-20.0,0.1575,105.0,0.1825); 
rectangle(fildes,0.0,0.1600,100.0,0.1800); 

text.alignment(fildes.TA.CENTER,TA.TOP,0.0,0.0); 
character.height(fildes,0.001); 

text2d(fildes,50.0,0.1588,"Time (seconds)",VDC.TEXT,FALSE); 

character.path(fildes.PATH.DOWN); 

text.alignment(fildes,TA.CENTER,TA.HALF,0.0,0.0); 

text2d(fildes,-14.0,0.1700,"Voltage",VDC.TEXT,FALSE); 

text.font_index(fildes,2); 

character.path(fildes,PATH.RIGHT); 

text.alignment(fildes,TA.CENTER,TA.BOTTOM,0.0,0.0); 

text2d(fildes,50.0,0.1810,"VOLTAGE VARIANCE",VDC.TEXT,FALSE); 

fp = fopenC'data", "r") ; 

while(i<200 && f scanf (fp, "°/ 0 f°/ 0 f",&coords [i] ,&coords [i + 1]) != EOF) 
i+=2; 

fclose(fp); 

polyline2d(fildes,coords,i/2,FALSE); 

text.alignment(fildes,TA.CENTER,TA.CONTINUOUS.VERTICAL,0.0,1.2); 
character.height(fildes,0.0006); 

x = 0.0; 
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sprintf (number, " # / 0 d n , (int)x) ; 

text2d(fildes,x,0.1598,number,VDC.TEXT,FALSE); 
for (i=10; i--;) { 

for (j =5; j--;) { 

move2d(fildes,x,0.1600); 
draw2d(fildes,x,0.1603); 
x += 2.0; 

> 

move2d(fildes,x,0.1600); 
draw2d(fildes,x,0.1605); 
sprintf (number , "°/ 0 d", (int)x) ; 

text2d(fildes,x,0.1600,number,VDC_TEXT,FALSE); 


text.alignment(fildes,TA_C0NTINU0US_H0RIZ0NTAL,TA_HALF,1.2,0.0); 
y = 0.1600; 

sprintf (number, ,,# / 0 5.4f " ,y) ; 

text2d(fildes,0.0,y,number,VDC_TEXT,FALSE); 

for (i=8; i--;) { 

for (j=5; j--;) { 

move2d(fildes,0.0,y); 
draw2d(fildes,1.0,y); 
y += 0.0005; 

> 

move2d(fildes,0.0,y); 

draw2d(fildes,2.0,y); 

sprintf (number , :: %5.4f :: , y) ; 

text2d(fildes,0.0,y,number,VDC_TEXT,FALSE); 


gclose(fildes); 
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Notes 
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Graphics with Fortran77 


Welcome 

This manual is designed to teach you how to use some fundamental procedures that are 
included in the Starbase Graphics Library on your HP-UX system. These procedures 
can be accessed from the C, Fortran77 and Pascal programming languages available for 
your system. This subsection will present a progressive example using the Fortran77 
Programming Language. The previous subsection covered the same material using the 
C Programming Language and the next subsection covers the same material using the 
Pascal programming language. 

Starbase Graphics programs written in Fortran77 require two conventions for procedure 
passing. 

1. All matrices passed to Starbase from Fortran77 must have the row and column 
indices reversed. Starbase assumes the order used by both Pascal and C for all 
matrices processed. 

2. Whenever passing strings as character* variables, or constants, the end of the string 
must be marked with a char(O) {NULL}. 

This manual was written with the assumption that you are familiar with your HP-UX 
Operating System, including the appropriate programming languages, compilers, linkers, 
editors, etc. If this is not the case, the information you need is available in the extensive 
documentation provided with your system. There are also many excellent books and 
courses available to provide information concerning C, Fortran77 and Pascal. 

This manual also assumes that you are familiar with basic computer graphics concepts. 
If this is not the case, there are many excellent books and courses available to provide 
this information. 

The example programs used in this tutorial are included with your system in the 
/usr/lib/starbase/demos directory. You are encouraged to run these programs as you 
read the manual. When you see how the programs work, modify them as you desire to 
see how each part contributes to the whole. Be aware that the example programs as¬ 
sume a system configuration which may differ from yours, and that the gopen procedure 
parameters and the device drivers linked to your program may need changing to match 
your system. 
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NOTE 


Demonstration programs and routines in /usr/lib/starbase/demos 
are for the purpose of instruction only. They are not part of the 
HP-UX package, and as such, they are not covered by any war¬ 
ranty, expressed or implied. Hewlett Packard shall not be liable 
for incidental or consequential damages in connection with, or aris¬ 
ing out of, the furnished, performance, or use of these routines. 


Preparation 

The directions concerning the execution of the example programs presented in this man¬ 
ual assumes your current directory is /usr/lib/starbase/demos. To make this directory 
your current working directory, use the change directory (cd) command as follows: 

cd /usr/lib/starbase/demos 

A discussion of the hierarchial directory structure used by the HP-UX Operating System 
is found in the Systems Administrator manual supplied with your system. 

For further details on the cd command, use the man command. For example. 

man cd 

The man command prints the reference page for the specified command on the display. 

The example programs presented in this manual are included with your operating system. 
They are located in the /usr/lib/starbase/demos directory. 

The examples are provided as source code. To read the code, use the HP-UX more or 
cat commands. To modify the code, use an appropriate editor, such as the vi editor. 

To execute the example programs on other devices, they must be compiled and linked to 
the correct drivers. The shell script shown below will accomplish this for you. 
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Device Drivers 

The Starbase device drivers are located in the directory /usr/lib and have file names 
appropriate to access by the “-1” option of the Fortran77 compiler (fc) command. 

Take a moment and list the device driver files in /usr/lib to see which device drivers are 
available with your system. All device driver file names begin with libdd prefix, followed 
by the device type. To list these files, type in: 

Is /usr/lib/libdd* 

As you can see, there are several drivers to choose from. 

The HP-GL device driver is /usr/lib/libddhpgl.a (accessed with -lddhpgl) and the 
HP 262x device driver is /usr/lib/libdd262x. a (accessed with -ldd262x). 

For further details concerning the Starbase Device Drivers, read the appropriate sections 
in the Starbase Device Drivers Library manual. 

A Shell Script 

The following shell script was used to compile and execute the example programs dis¬ 
cussed in this manual. The script works with both the Bourne Shell and the C Shell (the 
C shell calls the Bourne shell automatically). 

The “-1” option was used to reduce typing. This compiler option prepends /usr/lib/lib 
to the filename and appends . a to the file name. Thus, 

... -lddhpgl 

is processed as if it were 

... /usr/lib/libddhpgl.a 

The hp262x driver is included with the script. The sbl and sb2 files are included to 
resolve all unresolved variables generated by the Starbase programs. 

PR0G=$1 

shift 

fc -o $PROG $PROG.f $* -ldd262x -lsbl -lsb2 
$PROG 

This script is stored as an executable file under the file name FC in the 
/usr/lib/starbase/demos directory. 
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To compile and execute the example program examplelf .f, enter the following: 

FC examplelf 

To execute the compiled program examplelf again, type in: 

examplelf 

If you want the same program executed on an HP-GL plotter, you must edit the program 
and modify the gopen procedure call. 

To execute the example with other devices, you must link the correct devices to the 
program. 

For example, to link HP 98700 device driver to the example program, just type in: 

FC examplelf -ldd98700 
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The Data to be Plotted 

The following data is to be presented in graphical form. The example program to do this 
follows. 


Table 1-4. Test Data 


Test 

Value 

Test 

Value 

Test 

Value 

Test 

Value 

0 

0.1610 

1 

0.1625 

2 

0.1625 

3 

0.1628 

4 

0.1636 

5 

0.1631 

6 

0.1627 

7 

0.1608 

8 

0.1610 

9 

0.1606 

10 

0.1607 

11 

0.1617 

12 

0.1614 

13 

0.1626 

14 

0.1634 

15 

0.1640 

16 

0.1656 

17 

0.1660 

18 

0.1644 

19 

0.1651 

20 

0.1635 

21 

0.1641 

22 

0.1628 

23 

0.1619 

24 

0.1630 

25 

0.1624 

26 

0.1627 

27 

0.1644 

28 

0.1644 

29 

0.1657 

30 

0.1660 

31 

0.1670 

32 

0.1672 

33 

0.1666 

34 

0.1658 

35 

0.1662 

36 

0.1646 

37 

0.1633 

38 

0.1634 

39 

0.1636 

40 

0.1645 

41 

0.1652 

42 

0.1656 

43 

0.1677 

44 

0.1689 

45 

0.1680 

46 

0.1696 

47 

0.1680 

48 

0.1674 

49 

0.1677 

50 

0.1669 

51 

0.1655 

52 

0.1665 

53 

0.1662 

54 

0.1667 

55 

0.1668 

56 

0.1681 

57 

0.1688 

58 

0.1687 

59 

0.1707 

60 

0.1716 

61 

0.1716 

62 

0.1694 

63 

0.1698 

64 

0.1683 

65 

0.1683 

66 

0.1671 

67 

0.1681 

68 

0.1683 

69 

0.1684 

70 

0.1681 

71 

0.1698 

72 

0.1705 

73 

0.1723 

74 

0.1730 

75 

0.1734 

76 

0.1714 

77 

0.1722 

78 

0.1716 

79 

0.1696 

80 

0.1702 

81 

0.1699 

82 

0.1684 

83 

0.1706 

84 

0.1696 

85 

0.1715 

86 

0.1730 

87 

0.1737 

88 

0.1739 

89 

0.1751 

90 

0.1732 

91 

0.1747 

92 

0.1729 

93 

0.1717 

94 

0.1710 

95 

0.1707 

96 

0.1706 

97 

0.1709 

98 

0.1713 

99 

0.1720 
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The Data as a Clist 

The first column shows the first few file entries as a clist without move/draw indicators. 
The second column shows the first few data entries as a clist with move(l)/draw(0) 
indicators..-" 

Table 1-5. Test Data 


Clist without 
Move/Draw Indicators 

Clist with 

Move/Draw Indicators 

0 

0 

0.1610 

0.1610 

1 

0 (a move indicator) 

0.1625 

1 

2 

0.1625 

0.1625 

1 (a draw indicator) 

3 

2 

0.1628 

0.1625 

4 

1 (another draw indicator) 

0.1636 

3 

5 

0.1628 

0.1631 

1 

6 

4 

0.1627 

0.1636 

7 

1 

0.1608 

5 

8 

0.1631 

0.1610 

1 

9 

6 

0.1606 

0.1627 

10 

1 

0.1607 

7 

11 

0.1608 

0.1617 

1 

12 

8 

0.1614 

0.1610 

13 

1 

0.1626 

9 

14 

0.1606 

0.1634 

1 

15 

10 

0.1640 

0.1607 

16 

1 

0.1656 

11 

17 

0.1617 

0.1660 

1 

18 

12 

0.1644 

0.1614 

19 

1 

0.1651 

13 
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A Template Fortran77 Program 

The following is a template program that will be filled with Starbase procedure and 
function calls to draw the example voltage plot. As listed, this program opens the 
specified device, clears the clipping area and then closes the device. 


This program is stored as examplelf.f. 

include ’/usr/include/starbase.f1.h* 

program chart 

character NULL 

parameter(NULL = char(O)) 

include ’/usr/include/starbase.f2.h’ 


integer*4 fildes 

fildes = gopen(’/dev/tty’//NULL, OUTDEV, ’hp262x’//NULL, INIT) 
if (fildes .eq. -1) stop 

fildes = gclose(fildes) 
end 
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The Include File 

The files starbase.fi .h and starbase.f2.h contain the definitions and terms needed for 
any Starbase program written in Fortran77. These files are located in the /usr/include 
directory. 

To see what definitions and terms are needed, use the more command. The syntax is: 

more /usr/include/starbase.f1.h 

and 

more /usr/include/starbase.f2.h 

The Gopen Function 

The function gopen opens the specified graphic device. This function requires four pa¬ 
rameters: 

1. Device File Name - Device files are created by the System Administrator. Device 
files are located in the /dev directory. In the following examples, the device file tty 
is used. 

2. Performance Mode - This parameter may be one of the following: 

• OUTDEV - device driver is to output information to the device. 

• INDEV - device driver is to read information from the device. 

• OUTINDEV - device driver can send and receive information to and from the 
device. 

The following examples use OUTDEV since the example program is to be drawn on the 
output device’s display. 

3. Character Representation of the Driver Type - For the following example, this 
will be hp262x. This parameter identifies the driver to be used. The hp262x driver 
interrogates the device specified by the device file name and tests to see if the device 
is an HP 2623 Graphics Terminal or an HP 2627 Color Graphics Terminal, and acts 
accordingly. 

A possible character representation for an HP-GL plotter is hpgl. 
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4. Operation Mode - This parameter may be one of the following: 

0 - open the device, but do nothing else. 

INIT - open and initialize the device in a device dependent way. 

RESET - open and completely initialize the device. 

SPOOLED - open the device for spooled operation. Spooled output may be saved 
in a file for later display. 

THREE.D - open the device and set Starbase to 3-dimensional mode. 

These modes may be combined with the proper ADD syntax. In Fortran77 this is 
the plus sign (+) as in (INIT-f SPOOLED). 

By doing an ADD operation on INIT and SPOOLED, the graphic device can be opened, 
initialized and spooled to a file. 

For example: 

fildes = gopen("spoolfile",OUTDEV,"hpgl",INIT+SPOOLED); 

If the opening is not successful, gopen returns a value of -1. If the opening is successful, 
a positive integer (hie descriptor) is returned and the HP-GL device is initialized and 
ready for spooled output. 

Further information can be obtained about this procedure by using the man command. 
Just type in: 

man 3 gopen 

The Gclose Function 

To properly close a graphics device, use the gclose function. The fildes hie descriptor 
identihed by the gopen function is used to identify a particular device for all following 
Starbase procedures and functions, including gclose. 

Further information can be obtained about this procedure by using the man command. 
Just type in: 

man 3 gclose 
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A Review 

As a review, the following table lists information about the files, functions and commands 
just discussed. 

Table 1-6. A Review 


Required Items 

Learn More 

The cd Command 

/ usr / man/man 1 /cd. 1 
(man cd) 

The fc Compiler Command 

/ usr/man/man 1 /fc. 1 
(man fc) 

Shell Scripts 

HP-UX Concepts and Tutorials, 
volume 3. 

Device Drivers 

Starbase Device Drivers Library, 
/usr/lib/libdd* 

(Is /usr/lib/libdd...) 

C Programming 

The C Programming Language 
by Kernighan and Ritchie 

Definitions and Terms needed 
for any Starbase program 
written in Fortran77 

/ usr / include / starbase. f 1 .h 
/usr/include/starbase.f2.h 
(more /usr/include/starbase.f 1 .h) 
(more /usr/include/starbase.f2.h) 

gopen 

/ usr / man / man3 / gopen. 3 g 
(man 3 gopen) 

gclose 

/ usr/man / man3 / gclose. 3g 
(man 3 gclose) 


Virtual Device Coordinates 

The default Cartesian coordinate system used by the Starbase procedures is called the 
Virtual Device Coordinate (VDC) system. This system can be considered a 2-dimensional 
subset of the Cartesian plane with default x- and y-axis values ranging from 0.0 to 1.0. In 
3-dimensional graphics, this system can also be considered a subset of Cartesian 3-space 
with default x-, y- and z-axis values ranging from 0.0 to 1.0. Locations in VDC space 
are specified in VDC values as specified by the vdc_extent procedure. 


40 An Introduction to Starbase Graphics 




The procedure gopen automatically creates a Virtual Device Coordinate to Device Co¬ 
ordinate (DC) transformation matrix for each opened graphic device. All VDC data is 
processed through this matrix before being set to the target device. Since each device has 
a unique transformation matrix, the same data will appear as expected on each device. 

The range of values used for this system can be altered with the vdc_extent procedure. 

Use the push_vdc_matrix procedure to force the current working matrix to be the VDC 
to DC transformation matrix. 

Device Coordinates 

Device coordinate Space is the ("artesian 2-dimensional space that is the device's output 
surface. The range and magnitude of x- and y-axis values is defined by each device. 

Device Coordinate procedures bypass the VDC to DC transformation matrix. Such pro¬ 
cedures begin with the characters ric, for “device coordinate”. For example, dedraw will 
draw a line on the specified device using the untransformed coordinate values specified. 

To transform VDC values to DC values, use the vdc_to_dc procedure. 

World Coordinates 

World coordinates can have any value the user desires. This is handy when the data is 
to be used for purposes other than making a drawing. 

Since world coordinates can be of any value, they must be transformed to device co¬ 
ordinates before being drawn on a graphic device. This transformation can be done in 
several ways. For example: 

• A transformation matrix with the appropriate values to transform the World Co¬ 
ordinate data into Device Coordinate data may be supplied by the user. 

• A transformation matrix with the appropriate values to transform the World Coor¬ 
dinate data into Virtual Device Coordinate data may be supplied by the user. This 
matrix could then be concatenated (matrix multiplied) with the Virtual Device Co¬ 
ordinate to Device Coordinate transformation matrix to make a World Coordinate 
to Device Coordinate Matrix. 

For instance, in 2-dimensional mode, a matrix containing: 

cos 0 sin 0 

-sin 0 cos 0 

0 0 

will rotate world coordinates counter-clockwise by an angle of 6 . 
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• The Easiest Way is to use the vdc.extent procedure to change the ranges of values 
used to define the Virtual Device Coordinate Space so that the world coordinate 
values are now contained in VDC space. Any time the vdc.extent procedure is 
used, a new Virtual Device Coordinate to Device Coordinate matrix is calculated 
that maps Virtual Device Coordinate Space into Device Coordinate Space. 

Setting the VDC Extent 

In the example problem, we want to plot voltage values against the associated measure¬ 
ment number. Our voltage data ranges from just over 0.1600 through just under 0.1800, 
while we have 100 measurements (from 1 to 100). 

Logical values for the vdc extent would be -20 to 105 on the x-axis and 0.1575 to 0.1825 
in the y-axis. This will allow us to plot the data in a rectangle of size 0-100 on the x-axis 
and 0.1600-0.1800 on the y-axis and still leave room for labels within the vdc extent and 
outside the plotting area. Since we are doing 2-dimensional graphics, the z-coordinates 
are both 0.0. The syntax to do this is: 

call vdc.extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 

Detailed information on this procedure can be found using the HP-UX man command as 
follows: 

man 3 vdc_extent 


NOTE 

The decision was made to follow ANSI parameter patterns in the 
Starbase procedures. These parameter patterns are NOT CON¬ 
SISTENT. One procedure may call for xl,yl,zl,x2,y2,z2 while the 
next may require xl,x2,yl,y2,zl,z2. Hopefully this inconstancy will 
be removed from the ANSI standard and thus from the Starbase 
procedures. 
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Clipping 

Clipping is the process of not allowing selected graphic data to be displayed. There are 
two clipping processes: 

• Hard Clip - This is clipping done by the graphic output device that physically 
stops plotting outside the physical limits of the device’s display area. For example, 
a plotter’s pen can not draw past the physical edge of the plotter’s platen. 

• Soft Clip - This is clipping done by the graphics software to limit the visible portion 
of the plot. Soft clipping can be done to both 2-dimensional and 3-dimensional data. 

Starbase provides two clipping boundaries: 

• The Clip Rectangle - A rectangle can be specified with the clip.rectangle proce¬ 
dure that defines subsequent clipping boundaries. 

• The VDC Extent - The rectangle defined by the vdc_extent procedure can also be 
used to define subsequent clipping boundaries. 

The clip.indicator procedure identifies which of the two boundaries to clip to. 

The clip_depth procedure is used to define the front and back clipping planes for 
3-dimensional graphics. Front and back clipping is enabled or disabled with the 
depth_indicator procedure. 
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Isotropic (undistorted) Mapping 

Isotropic mapping is when one unit in the x-axis exactly equals one unit in the y-axis. 
This is sometimes referred to as undistorted plotting. 

The mapping_mode procedure sets the mapping mode to either anisotropic or isotropic 
plotting mode. The default is isotropic. 

The following example program draws an isotropic square around the default Virtual 
Device Coordinate space. This program is in file example2f.f. 

include */usr/include/starbase. f 1. h ’ 

program chart 

character NULL 

parameter(NULL = char(O)) 

include ’/usr/include/starbase.f2.h * 

integer*4 fildes 

tildes = gopenC/dev/tty7/NULL, OUTDEV, ’hp262x’//NULL, INIT) 
if (fildes .eq. -1) stop 

call interior_style(fildes,INT_H0LL0W,TRUE) 
call rectangle(fildes,0.0,0.0,1.0,1.0) 

fildes = gclose(fildes) 
end 
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Figure 1-9. An Isotropic Frame of VDC Space 
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Anisotropic (distorted) Mapping 

Anisotropic mapping where one unit in the X direction does not have to equal one unit 
in the Y direction. This is sometimes called distorted plotting. 

The mapping.mode procedure sets the mapping mode to either anisotropic or isotropic 
plotting mode. The following single line was added to the preceeding isotropic program 
and the anisotropic results are shown Figure 1-10. The rectangle still frames the VDC 
default space, but now the space fills the usable portion of the display. This program is 
in exampleSf.f. 

call mapping_mode(fiIdes.TRUE); 



Since the scale for the voltage measurements is not the same as the scale for the number 
of measurements, anisotropic plotting is appropriate. 
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Viewports 

The viewport is the portion of the output display that is used to draw the picture. This 
can be all or only a part of the display. 

The viewport boundaries is defined by several procedures. 

• set_pl_p2 - This procedure defines the physical region that contains the viewport. 

• mapping.mode - This procedure defines the viewport as isotropic (distorted) or 
anisotropic (undistorted). If anisotropic, the viewport is the same as the rect¬ 
angle defined by the set_pl_p2 procedure. If the viewport is isotropic, the viewport 
is the largest rectangle with the same aspect ratio as the VDC extent that will 
fit in the rectangle defined by the set_pl_p2 procedure and is positioned in that 
rectangle by the viewport.justification procedure. 

• viewport.justif ication - This procedure defines the fraction of “white space” (the 
area of the set_pl.p2 rectangle not within the viewport) to the left or bottom of 
the viewport. The default is .5 (50%), so the viewport is centered in the rectangle 
defined by set_pl_p2. This procedure only applies to isotropic viewports. 
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Rectangles 

The rectangle procedure provides an easy way to draw rectangles. All you need to 
specify is the device needing a rectangle and the coordinates of two opposite corners of 
the rectangle. A default rectangle has a filled interior and no perimeter. 

To see the extent of the Virtual Device Coordinate Space and to draw a frame around 
the location on the display, two rectangles are drawn. The syntax for these rectangles is: 

call rectangle(fildes,-20,0.1575,105.0,0.1825); 
call rectangle(fildes,0,0.1600,100.0,0.1800); 

To make rectangles hollow, and add the perimeter, use the interior_style procedure. 
The following syntax will do the job. 

call interior_style(fildes,INT_H0LL0W,TRUE); 

The following program segment is added to the program in order to draw the rectangles. 
The program is stored as example4f-f- 

include Vusr/include/starbase.f1.h’ 

program chart 

character NULL 

parameter(NULL = char(0)) 

include */usr/include/starbase. f 2. h ’ 

integer*4 fildes, status 

fildes = gopen(*/dev/tty*//NULL, OUTDEV, ’hp262x 7/NULL, INIT) 
if (fildes .eq. -1) stop 

call vdc_extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0) 
call clip.rectangle(fildes, -20.0,105.0,0.1575,0.1825) 
call mapping_mode(fildes,TRUE) 

call interior.style(fildes,INT_H0LL0W,TRUE) 
call rectangle(fildes,-20.0,0.1575,105.0,0.1825) 
call rectangle(fildes,0.0,0.1600,100.0,0.1800) 

status = gclose(fildes) 
end 
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Figure 1-11. Two Rectangles 
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Plotting the Data 

The following program will read the plot data from the file data and draw the results 
in Virtual Device Coordinate space. The main procedure is polyline which will move 
the graphics pen to the first (X,Y) data location and then draw to the remaining data 
locations. The data is read into a single-dimension array usable by polyline. The number 
of points to be drawn to is i/2 and the FALSE flag indicates that there are no move-draw 
(0 for move, 1 for draw) indicators in the data. 

The syntax is: 

include ’/usr/include/starbase.f1.h’ 

program chart 

character NULL 

parameter(NULL = char(O)) 

include ’/usr/include/starbase. f 2. h ’ 

integer*4 fildes 
integer*4 i, j 
real x, y 
real coords(200) 

fildes = gopen C/dev/tty 7/NULL, OUTDEV, ’hp262x 7/NULL, INIT) 
if (fildes .eq. -1) stop 

call vdc.extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0) 
call clip.rectangle(fildes,-20.0,105.0,0.1575,0.1825) 
call mapping_mode(fildes.TRUE) 

call interior.style(fildes,INT_H0LL0W,TRUE) 
call rectangle(fildes,0.0,0.1575,105.0,0.1825) 
call rectangle(fildes,0.0,0.1600,100.0,0.1800) 

open (unit=9,file=’data’) 
do i=l,199,2 

read(9,*,end=20) coords(i),coords(i+1) 

end do 

20 close(9) 

call polyline2d(fildes,coords,i/2,FALSE) 

fildes = gclose(fildes) 
end 
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The results of this modification to the example program are shown in Figure 1-12. This 
drawing was made with example5f.f. 



Figure 1-12. Plotted Data 
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Labels 

Let us now label the drawing. We will use two fonts, different character paths, and 
different text alignments to show some of the capabilities of the system. 

The syntax to do this is: 

include ’/usr/include/starbase. f 1. h ’ 

program chart 

character NULL 

parameter(NULL = char(O)) 

include ’/usr/include/starbase. f 2 . h ’ 

integer*4 fildes 
integer*4 i, j 
real x, y 
real coords(200) 
character*80 number 

fildes = gopen(’/dev/tty’//NULL, OUTDEV, ’hp262x’//NULL, INIT) 
if (fildes .eq. -1) stop 

call vdc_extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0) 
call clip_rectangle(fildes,-20.0,105.0,0.1575,0.1825) 
call mapping_mode(fildes.TRUE) 

call interior.style(fildes,INT_H0LL0W.TRUE) 
call rectangle(fildes,-20.0,0.1575,105.0,0.1825) 
call rectangle(fildes,0.0,0.1600,100.0,0.1800) 

call text.alignment(fildes,TA.CENTER,TA.TOP,0.0,0.0) 
call character.height(fildes,0.001) 

call text2d(fildes,50.0,0.1588,’Time (seconds)’//NULL.VDC.TEXT, 

+ FALSE) 

call character_path(fildes,PATH.D0WN) 

call text.alignment(fildes,TA.CENTER,TA.HALF,0.0,0.0) 

call text2d(fildes,-14.0,0.1700,’Voltage’//NULL,VDC.TEXT,FALSE) 

call text.font_index(fildes,2) 

call character_path(fildes,PATH.RIGHT) 

call text.alignment(fildes,TA.CENTER,TA.B0TT0M,0.0,0.0) 

call text2d(fildes,50.0,0.1810,’VOLTAGE VARIANCE’//NULL,VDC.TEXT, 

+ FALSE) 

open (unit=9,file=’data’) 
do i=l,199,2 

read(9,*,end=20) coords(i),coords(i+1) 

end do 

20 close(9) 
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call polyline2d(fildes,coords,i/2,FALSE) 

fildes = gclose(fildes) 
end 

Our example is now shown Figure 1-13. This program is stored in exampledf.f. 



Figure 1-13. A Labeled Plot 
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Tic Marks 

We now need to add the numerated tic marks. This is done with two loops. We use 
write to change the tic mark numbers into strings to be drawn as text. 

call text.alignment(fildes,TA.CENTER, 

+ T A _ CO NTINUOUS _VERTICAL,0.0,1.2) 

call character.height(fildes,0.0006) 

x = 0.0 

write(unit-number,fmt=*(13)’) int(x) 

call text2d(fildes, x, 0.1598,number(1:3)//NULL,VDC.TEXT,FALSE) 
do i=l r 10 

do j=l,5 

call move2d(fildes,x,0.1600) 
call draw2d(fildes,x,0.1603) 
x = x + 2.0 

end do 

call move2d(fildes,x,0.1600) 
call draw2d(fildes,x,0.1605) 
write(unit=number,fmt=’(13)’) int(x) 
call text2d(fildes, x, 0.1600,number(1:3)//NULL,VDC.TEXT,FALSE) 
end do 

call text.alignment(fildes, 

+ TA_C0NTINU0US_H0RIZ0NTAL,TA.HALF,1.2,0.0) 

y = 0.1600 

write(unit=number,fmt=’(f5.4)*) y 

call text2d(fildes,0.0,y,number(1:5)//NULL,VDC.TEXT,FALSE) 
do i=l,8 

do j =1,5 

call move2d(fildes,0.0,y) 
call draw2d(fildes,1.0,y) 
y = y + 0.0005 

end do 

call move2d(fildes,0.0,y) 
call draw2d(fildes,2.0,y) 
write(unit=number,fmt-*(f5.4)*) y 
call text2d(fildes,0.0,y,number(1:5)//NULL,VDC.TEXT,FALSE) 
end do 
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The Final Picture 



Figure 1-14. The Final Plot 
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The Whole Program 

include ’/usr/include/starbase.f1.h’ 

program chart 

character NULL 

parameter(NULL = char(O)) 

include ’/usr/include/starbase. f 2. h ’ 

integer*4 fildes 
integer*4 i, j 
real x, y 
real coords(200) 
character*80 number 

fildes = gopen(’/dev/tty *//NULL, OUTDEV, ’hp262x’//NULL, INIT) 
if (fildes .eq. -1) stop 

call vdc.extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0) 
call clip_rectangle(fildes,-20.0,105.0,0.1575,0.1825) 
call mapping_mode(fildes,TRUE) 

call interior_style(fildes,INT.HOLLOW,TRUE) 
call rectangle(fildes,-20.0,0.1575,105.0,0.1825) 
call rectangle(fildes,0.0,0.1600,100.0,0.1800) 

call text_alignment(fildes,TA_CENTER,TA_T0P,0.0,0.0) 
call character_height(fildes,0.001) 

call text2d(fildes,50.0,0.1588,’Time (seconds)’//NULL.VDC.TEXT, 

+ FALSE) 

call character_path(fildes,PATH_D0WN) 

call text.alignment(fildes,TA.CENTER,TA.HALF,0.0,0.0) 

call text2d(fildes,-14.0,0.1700,*Voltage’//NULL,VDC.TEXT,FALSE) 

call text.font_index(fildes,2) 
call character.path(fildes,PATH.RIGHT) 
call text.alignment(fildes,TA.CENTER,TA.BOTTOM,0.0,0.0) 
call text2d(fildes,50.0,0.1810,’VOLTAGE VARIANCE’//NULL,VDC.TEXT, 
+ FALSE) 

open (unit=9,file=’data’) 
do i=l,199,2 

read(9,*,end=20) coords(i),coords(i+1) 

end do 

20 close(9) 

call polyline2d(fildes,coords,i/2.FALSE) 

call text.alignment(fildes,TA.CENTER, 

+ TA.CONTINUOUS.VERTICAL,0.0,1.2) 

call character.height(fildes,0.0006) 
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x = 0.0 

write(unit=number,fmt=*(13)*) int(x) 

call text2d(fildes,x,0.1598,number(1:3)//NULL,VDC.TEXT,FALSE) 
do i=l,10 

do j=l,5 

call move2d(fildes,x,0.1600) 
call draw2d(fildes,x,0.1603) 
x = x + 2.0 

end do 

call move2d(fildes,x,0.1600) 
call draw2d(fildes,x,0.1605) 
write(unit=number,fmt= *(13)’) int(x) 
call text2d(fildes,x,0.1600,number(1:3)//NULL,VDC.TEXT,FALSE) 
end do 

call text_alignment(fildes, 

+ TA_C0NTINU0US_H0RIZ0NTAL,TA.HALF,1.2,0.0) 

y = 0.1600 

write(unit=number,fmt= *(f5.4)’) y 

call text2d(fildes,0.0,y,number(1:5)//NULL,VDC.TEXT,FALSE) 
do i=l,8 

do j=l,5 

call move2d(fildes,0.0,y) 
call draw2d(fildes,1.0,y) 
y = y + 0.0005 

end do 

call move2d(fildes,0.0,y) 
call draw2d(fildes,2.0,y) 
write(unit=number,fmt=’(f5.4) ’) y 
call text2d(fildes,0.0,y,number(1:5)//NULL,VDC.TEXT,FALSE) 
end do 

fildes = gclose(fildes) 
end 
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Notes 
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Graphics with Pascal 


Welcome 

This manual is designed to teach you how to use some fundamental procedures that are 
included in the Starbase Graphics Library on your HP-UX system. These procedures can 
be accessed from the C, Fortran77 and Pascal programming languages available for your 
system. This subsection will present a progressive example using the C Programming 
Language. The previous subsections covered the same material using the C and Fortran77 
Programming Languages. 

This manual was written with the assumption that you are familiar with your HP-UX 
Operating System, including the appropriate programming languages, compilers, linkers, 
editors, etc. If this is not the case, the information you need is available in the extensive 
documentation provided with your system. There are also many excellent books and 
courses available to provide information concerning C, Fortran77 and Pascal. 

This manual also assumes that you are familiar with basic computer graphics concepts. 
If this is not the case, there are many excellent books and courses available to provide 
this information. 

The example programs used in this tutorial are included with your system in the 
/usr/lib/starbase/demos directory. You are encouraged to run these programs as you 
read the manual. When you see how the programs work, modify them as you desire to 
see how each part contributes to the whole. Be aware that the example programs as¬ 
sume a system configuration which may differ from yours, and that the gopen procedure 
parameters and device drivers linked to your program may need changing to match your 
system. 


NOTE 

Demonstration programs and routines in /usr/lib/starbase/demos 
are for the purpose of instruction only. They are not part of the 
HP-UX package, and as such, they are not covered by any war¬ 
ranty, expressed or implied. Hewlett Packard shall not be liable 
for incidental or consequential damages in connection with, or aris¬ 
ing out of, the furnished, performance, or use of these routines. 
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Preparation 

The directions concerning the execution of the example programs presented in this man¬ 
ual assumes your current directory is /usr/lib/starbase/demos. To make this directory 
your current working directory, use the change directory (cd) command as follows: 

cd /usr/lib/starbase/demos 

A discussion of the hierarchial directory structure used by the HP-UX Operating System 
is found in the Systems Administrator manual supplied with your system. 

For further details on the cd command, use the man command. For example, 
man cd 

The man command prints the reference page for the specified command on the display. 

The example programs presented in this manual are included with your operating system. 
They are located in the /usr/lib/starbase/demos directory. 

The examples are provided as source code. To read the code, use the HP-UX more or 
cat commands. To modify the code, use an appropriate editor, such as the vi editor. 

To execute the example programs on other devices, they must be compiled and linked to 
the correct drivers. The shell script shown below will accomplish this for you. 

Device Drivers 

The Starbase device drivers are located in the directory /usr/lib and have file names 
appropriate to access by the “-1” option of the Pascal compiler (pc) command. 

Take a moment and list the device driver files in /usr/lib to see which device drivers are 
available with your system. All device driver file names begin with libdd prefix, followed 
by the device type. To list these files, type in: 

Is /usr/lib/libdd* 

As you can see, there are several drivers to choose from. 

The HP-GL device driver is /usr/lib/libddhpgl. a (accessed with -lddhpgl) and the 
HP 262x device driver is /usr/lib/libdd262x. a (accessed with -ldd262x). These are the 
device drivers included in the example programs. 

For further details concerning the Starbase Device Drivers, read the appropriate sections 
in the Starbase Device Drivers Library manual. 
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A Shell Script 

The following shell script was used to compile and execute the example programs dis¬ 
cussed in this manual. The script works with both the Bourne Shell and the C Shell (the 
C shell calls the Bourne shell automatically). 

The “-1” option was used to reduce typing. This compiler option prepends /usr/lib/lib 
to the filename and appends .a to the file name. Thus, 

... -lddhpgl 

is processed as if it were 

... /usr/lib/libddhpgl.a 

The HP262x device driver is linked by the script. The sbl and sb2 files are included to 
resolve all unresolved variables generated by the Starbase programs. 

PR0G=$1 

shift 

pc -o $PROG $PROG.p $* -ldd262x -lsbl -lsb2 
$PROG 

This script is stored as an executable file under the file name PC in the 
/usr/lib/starbase/demos directory. 

To compile and execute the example program examplelp.p, enter the following: 

PC examplelp 

To execute the compiled program examplelp again, type in: 

examplelp 

If you want the same program executed on an HP-GL plotter, the gopen procedure 
parameters must be modified. 

To execute the example with other devices, you must link the correct devices to the 
program. 

For example, to execute to link the HP 98700 device driver, just type in: 

PC examplelp -ldd98700 
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The Data to be Plotted 

The following data is to be presented in graphical form. The example program to do this 
follows. 


Table 1-7. Test Data 


Test 

Value 

Test 

Value 

Test 

Value 

Test 

Value 

0 

0.1610 

1 

0.1625 

2 

0.1625 

3 

0.1628 

4 

0.1636 

5 

0.1631 

6 

0.1627 

7 

0.1608 

8 

0.1610 

9 

0.1606 

10 

0.1607 

11 

0.1617 

12 

0.1614 

13 

0.1626 

14 

0.1634 

15 

0.1640 

16 

0.1656 

17 

0.1660 

18 

0.1644 

19 

0.1651 

20 

0.1635 

21 

0.1641 

22 

0.1628 

23 

0.1619 

24 

0.1630 

25 

0.1624 

26 

0.1627 

27 

0.1644 

28 

0.1644 

29 

0.1657 

30 

0.1660 

31 

0.1670 

32 

0.1672 

33 

0.1666 

34 

0.1658 

35 

0.1662 

36 

0.1646 

37 

0.1633 

38 

0.1634 

39 

0.1636 

40 

0.1645 

41 

0.1652 

42 

0.1656 

43 

0.1677 

44 

0.1689 

45 

0.1680 

46 

0.1696 

47 

0.1680 

48 

0.1674 

49 

0.1677 

50 

0.1669 

51 

0.1655 

52 

0.1665 

53 

0.1662 

54 

0.1667 

55 

0.1668 

56 

0.1681 

57 

0.1688 

58 

0.1687 

59 

0.1707 

60 

0.1716 

61 

0.1716 

62 

0.1694 

63 

0.1698 

64 

0.1683 

65 

0.1683 

66 

0.1671 

67 

0.1681 

68 

0.1683 

69 

0.1684 

70 

0.1681 

71 

0.1698 

72 

0.1705 

73 

0.1723 

74 

0.1730 

75 

0.1734 

76 

0.1714 

77 

0.1722 

78 

0.1716 

79 

0.1696 

80 

0.1702 

81 

0.1699 

82 

0.1684 

83 

0.1706 

84 

0.1696 

85 

0.1715 

86 

0.1730 

87 

0.1737 

88 

0.1739 

89 

0.1751 

90 

0.1732 

91 

0.1747 

92 

0.1729 

93 

0.1717 

94 

0.1710 

95 

0.1707 

96 

0.1706 

97 

0.1709 

98 

0.1713 

99 

0.1720 


62 An Introduction to Starbase Graphics 




The Data as a Clist 

The first column shows the first few file entries as a clist without move/draw indicators. 
The second column shows the first few data entries as a clist with move(l)/draw(0) 
indicators. 

Table 1-8. Data in Clist Format 


Clist without 
Move/Draw Indicators 

Clist with 

Move/Draw Indicators 

0 

0 

0.1610 

0.1610 

1 

0 (a move indicator) 

0.1625 

1 

2 

0.1625 

0.1625 

1 (a draw indicator) 

3 

2 

0.1628 

0.1625 

4 

1 (another draw indicator) 

0.1636 

3 

5 

0.1628 

0.1631 

1 

6 

4 

0.1627 

0.1636 

7 

1 

0.1608 

5 

8 

0.1631 

0.1610 

1 

9 

6 

0.1606 

0.1627 

10 

1 

0.1607 

7 

11 

0.1608 

0.1617 

1 

12 

8 

0.1614 

0.1610 

13 

1 

0.1626 

9 

14 

0.1606 

0.1634 

1 

15 

10 

0.1640 

0.1607 

16 

1 

0.1656 

11 

17 

0.1617 

0.1660 

1 

18 

12 

0.1644 

0.1614 

19 

1 

0.1651 

13 
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The Results Desired 

The following picture shows the plot to be created by the example programs described 
in the subsection. 



Figure 1-15. The Results Desired 
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A Template Pascal Program 

The following is a template program that will be filled with Starbase procedure and 
function calls to draw the example voltage plot. As listed, this program opens the 
specified device, clears the clipping area and then closes the device. The capability of 
executing the program on an HP262x Graphics Terminal or a specified device is included. 

This program is stored as examplelp.p. 

program main(input,output); 

$include ’/usr/include/starbase.pi.h * $ 
var 

fildes, status : integer; 

$include ’/usr/include/starbase.p2.h’$ 
procedure exit(result: integer); external; 

begin {main} 

fildes:=gopen(’/dev/tty’.OUTDEV,’hp262x’,INIT); 
if fildes = -1 then exit(-l); 

status := gclose(fildes); 
end. 

Tk« Im^Iii#Ia CSIac 

■ ■ ■ 'W' MIIVUilMV ■ ■ ■ 'W 

The files starbase.pl.h and starbase.p2.h contain the definitions and terms needed for 
any Starbase program written in Pascal. These files are located in the /usr/include 
directory. 

To see what definitions and terms are needed, use the more command. The syntax is: 

more /usr/include/starbase.pi.h 

and 

more /usr/include/starbase.p2.h 
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The Gopen Function 

The function gopen opens the specified graphic device. This function requires four pa¬ 
rameters: 

1. Device File Name - Device files are created by the System Administrator. Device 
files are located in the /dev directory. In the following examples, the device file tty 
is used. 

2. Performance Mode - This parameter may be one of the following: 

• OUTDEV - device driver is to output information to the device. 

• INDEV - device driver is to read information from the device. 

• OUTINDEV - device driver can send and receive information to and from the 
device. 

The following examples use OUTDEV since the example program is to be drawn on the 
output device’s display. 

3. Character Representation of the Driver Type - For the following example, this 
will be hp262x. This parameter identifies the driver to be used. The hp262x driver 
interrogates the device specified by the device file name and tests to see if the device 
is an HP 2623 Graphics Terminal or an HP 2627 Color Graphics Terminal, and acts 
accordingly. 

A possible character representation for an HP-GL plotter is hpgl. 

4. Operation Mode - This parameter may be one of the following: 

0 - open the device, but do nothing else. 

INIT - open and initialize the device in a device dependent way. 

RESET - open and completely initialize the device. 

SPOOLED - open the device for spooled operation. Spooled output may be saved 
in a file for later display. 

THREE.D - open the device and set Starbase to 3-dimensional mode. 

These modes may be combined with the proper ADD syntax. In Pascal this is the 
plus sign (+) as in (INIT+SPOOLED). 

By doing an ADD operation on INIT and SPOOLED, the graphic device can be opened, 
initialized and spooled to a file. 
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For example: 

fildes = gopen(’spoolfile’,OUTDEV,’hpgl’,INIT+SPOOLED); 

If the opening is not successful, gopen returns a value of -1. If the opening is successful, 
a positive integer (file descriptor) is returned and the HP-GL device is initialized and 
ready for spooled output. 

Further information can be obtained about this procedure by using the man command. 
Just type in: 

man 3 gopen 

The Gclose Function 

To properly close a graphics device, use the gclose function. The fildes file descriptor 
identified by the gopen function is used to identify a particular device for all following 
Starbase procedures and functions, including gclose. 

Further information can be obtained about this procedure by using the man command. 
Just type in: 

man 3 gclose 
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A Review 

As a review, the following table lists information about the files, functions and commands 
just discussed. 

Table 1-9. A Review 


Required Items 

Learn More 

The cd Command 

/usr/man / manl/cd. 1 
(man cd) 

The pc Compiler Command 

/usr/man/manl/pc.l 
(man pc) 

Shell Scripts 

HP-UX Concepts and Tutorials, 
volume 3. 

Device Drivers 

Starbase Device Drivers Library, 
/usr/lib/libdd* 

(Is /usr/lib/libdd...) 

Definitions and Terms needed 
for any Starbase program 
written in Pascal. 

/ usr / include / starbase.p 1 .h 
/ usr / include / starbase.p2.h 
(more /usr/include/starbase.p 1 .h) 
(more /usr/include/starbase.p2.h) 

gopen 

/ usr / man / man3 / gopen .3g 
(man 3 gopen) 

gclose 

/ usr / man / man3 / gclose.3g 
(man 3 gclose) 


Virtual Device Coordinates 

The default Cartesian coordinate system used by the Starbase procedures is called the 
Virtual Device Coordinate (VDC) system. This system can be considered a 2-dimensional 
subset of the Cartesian plane with default x- and y-axis values ranging from 0.0 to 1.0. In 
3-dimensional graphics, this system can also be considered a subset of Cartesian 3-space 
with default x-, y- and z-axis values ranging from 0.0 to 1.0. Locations in VDC space 
are specified in VDC values as specified by the vdc_extent procedure. 
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The procedure gopen automatically creates a Virtual Device Coordinate to Device Co¬ 
ordinate (DC) transformation matrix for each opened graphic device. All VDC data is 
processed through this matrix before being set to the target device. Since each device has 
a unique transformation matrix, the same data will appear as expected on each device. 

The range of values used for this system can be altered with the vdc_extent procedure. 

Use the push_vdc_matrix procedure to force the current working matrix to be the VDC 
to DC transformation matrix. 

Device Coordinates 

Device coordinate Space is the Cartesian 2-dimensional space that is the device’s output 
surface. The range and magnitude of x- and y-axis values is defined by each device. 

Device Coordinate procedures bypass the VDC to DC transformation matrix. Such pro¬ 
cedures begin with the characters dc, for “device coordinate”. For example, dedraw will 
draw a line on the specified device using the untransformed coordinate values specified. 

To transform VDC values to DC values, use the vdc_to_dc procedure. 

World Coordinates 

World coordinates can have any value the user desires. This is handy when the data is 
to be used for purposes other than making a drawing. 

Since world coordinates can be of any value, they must be transformed to device co¬ 
ordinates before being drawn on a graphic device. This transformation can be done in 
several ways. For example: 

• A transformation matrix with the appropriate values to transform the World Co¬ 
ordinate data into Device Coordinate data may be supplied by the user. 

• A transformation matrix with the appropriate values to transform the World Coor¬ 
dinate data into Virtual Device Coordinate data may be supplied by the user. This 
matrix could then be concatenated (matrix multiplied) with the Virtual Device Co¬ 
ordinate to Device Coordinate transformation matrix to make a World Coordinate 
to Device Coordinate Matrix. 

For instance, in 2-dimensional mode, a matrix containing: 

cos 6 sin 0 

-sin 6 cos 0 

0 0 

will rotate world coordinates counter-clockwise by an angle of 0. 
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• The Easiest Way is to use the vdc.extent procedure to change the ranges of values 
used to define the Virtual Device Coordinate Space so that the world coordinate 
values are now contained in VDC space. Any time the vdc_extent procedure is 
used, a new Virtual Device Coordinate to Device Coordinate matrix is calculated 
that maps Virtual Device Coordinate Space into Device Coordinate Space. 

Setting the VDC Extent 

In the example problem, we want to plot voltage values against the associated measure¬ 
ment number. Our voltage data ranges from just over 0.1600 through just under 0.1800, 
while we have 100 measurements (from 1 to 100). 

Logical values for the vdc extent would be -20 to 105 on the x-axis and 0.1575 to 0.1825 
in the y-axis. This will allow us to plot the data in a rectangle of size 0-100 on the x-axis 
and 0.1600-0.1800 on the y-axis and still leave room for labels within the vdc extent and 
outside the plotting area. Since we are doing 2-dimensional graphics, the z-coordinates 
are both 0.0. The syntax to do this is: 

vdc.extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 

Detailed information on this procedure can be found using the HP-UX man command as 
follows: 

man 3 vdc.extent 


NOTE 

The decision was made to follow ANSI parameter patterns in the 
Starbase procedures. These parameter patterns are NOT CON¬ 
SISTENT. One procedure may call for xl,yl,zl,x2,y2,z2 while the 
next may require xl,x2,yl,y2,zl,z2. Hopefully this inconstancy will 
be removed from the ANSI standard and thus from the Starbase 
procedures. 
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Clipping 

Clipping is the process of not allowing selected graphic data to be displayed. There are 
two clipping processes: 

• Hard Clip - This is clipping done by the graphic output device that physically 
stops plotting outside the physical limits of the device’s display area. For example, 
a plotter’s pen can not draw past the physical edge of the plotter’s platen. 

• Soft Clip - This is clipping done by the graphics software to limit the visible portion 
of the plot. Soft clipping can be done to both 2-dimensional and 3-dimensional data. 

Starbase provides two clipping boundaries: 

• The Clip Rectangle - A rectangle can be specified with the clip_rectangle proce¬ 
dure that defines subsequent clipping boundaries. 

• The VDC Extent - The rectangle defined by the vdc.extent procedure can also be 
used to define subsequent clipping boundaries. 

The clip, indie at or procedure identifies which of the two boundaries to clip to. 

The clip.depth procedure is used to define the front and back clipping planes for 
3-dimensional graphics. Front and back clipping is enabled or disabled with the 
depth.indicator procedure. 
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Isotropic (undistorted) Mapping 

Isotropic mapping is when one unit in the x-axis exactly equals one unit in the y-axis. 
This is sometimes referred to as undistorted plotting. 

The mapping_mode procedure sets the mapping mode to either anisotropic or isotropic 
plotting mode. The default is isotropic. 

The following example program draws an isotropic square around the default Virtual 
Device Coordinate space. This program is in hie example2p.p. 

program main(input,output); 

$include */usr/include/starbase.pi.h*$ 

var 

fildes: integer; 

$include */usr/include/starbase.p2.h * $ 
procedure exit(result: integer); external; 

begin {main} 

fildes:=gopen(*/dev/tty’.OUTDEV,’hp262x’,INIT); 
if fildes = -1 then exit(-l); 

interior_style(fildes,INT_H0LL0W,1); 
rectangle(fildes,0.0,0.0,1.0,1.0); 

fildes := gclose(fildes); 

end. 
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Figure 1-16. An Isotropic Frame of VDC Space 
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Anisotropic (distorted) Mapping 

Anisotropic mapping where one unit in the X direction does not have to equal one unit 
in the Y direction. This is sometimes called distorted plotting. 

The mapping_mode procedure sets the mapping mode to either anisotropic or isotropic 
plotting mode. The following single line was added to the preceeding isotropic program 
and the anisotropic results are shown in Figure 1-17. The rectangle still frames the VDC 
default space, but now the space fills the usable portion of the display. This program is 
in exampleSp.p. 

mapping_mode(fildes,1); 



Since the scale for the voltage measurements is not the same as the scale for the number 
of measurements, anisotropic plotting is appropriate. 
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Viewports 

The viewport is the portion of the output display that is used to draw the picture. This 
can be all or only a part of the display. 

The viewport boundaries is defined by several procedures. 

• set_pl_p2 - This procedure defines the physical region that contains the viewport. 

• mapping.mode - This procedure defines the viewport as isotropic (distorted) or 
anisotropic (undistorted). If anisotropic, the viewport is the same as the rect¬ 
angle defined by the set_pl_p2 procedure. If the viewport is isotropic, the viewport 
is the largest rectangle with the same aspect ratio as the VDC extent that will 
fit in the rectangle defined by the set_pl_p2 procedure and is positioned in that 
rectangle by the viewport.justif ication procedure. 

• viewport.justification - This procedure defines the fraction of “white space” (the 
area of the set_pl_p2 rectangle not within the viewport) to the left or bottom of 
the viewport. The default is .5 (50%), so the viewport is centered in the rectangle 
defined by set_pl_p2. This procedure only applies to isotropic viewports. 
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Rectangles 

The rectangle procedure provides an easy way to draw rectangles. All you need to 
specify is the device needing a rectangle and the coordinates of two opposite corners of 
the rectangle. A default rectangle has a filled interior and no perimeter. 

The syntax for drawing two rectangles, one to enclose the vdc extent and the other to 
enclose our plotting area is shown below. 

rectangle(fildes,-20,0.1575,105.0,0.1825); 
rectangle(fildes,0,0.1600,100.0,0.1800); 

To make rectangles hollow, and add the perimeter, use the interior_style procedure. 
The following syntax will do the job. 

interior_style(fildes,INT_H0LL0W,1); 

The following program segment is added to the program in order to draw the rectangles. 
The program is stored as exampleJ^p.p. 

program main(input,output); 

$include ’/usr/include/starbase.pi.h * $ 

const 

var 

fildes : integer; 

$include */usr/include/starbase.p2.h’$ 
procedure exit(result: integer); external; 

begin {main} 

fildes:=gopen(’/dev/tty *.OUTDEV,’hp262x’,INIT); 
if fildes = -1 then exit(-l); 

vdc_extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 
clip_rectangle(fildes,-20.0,105.0,0.1575,0.1825); 
mapping_mode(fildes,1); 

interior_style(fildes,INT_H0LL0W,1); 
rectangle(fildes,-20.0,0.1575,105.0,0.1825); 
rectangle(fildes,0.0,0.1600,100.0,0.1800); 

fildes := gclose(fildes); 

end. 
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To see the extent of the Virtual Device Coordinate Space, and to draw a frame around 
the location on the display, two rectangles are drawn. 



Figure 1-18. Two Rectangles 
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Plotting the Data 

The following program will read the plot data from the file data and draw the results 
in Virtual Device Coordinate space. The main procedure is polyline which will move 
the graphics pen to the first (X,Y) data location and then draw to the remaining data 
locations. The data is read into a single-dimension array usable by polyline. The number 
of points to be drawn to is i/2 and the 0 flag indicates that there are no move-draw (0 
for move, 1 for draw) indicators in the data. 

The syntax is: 

program main(input,output); 

$include */usr/include/starbase.pi.h * $ 
const 

array.size = 200; 


type 

array_type = array[0..array_size] of real; 


var 

fildes, i : integer; 
coords: array_type; 
data: text; 

$include */usr/include/starbase.p2.h * $ 
procedure exit(result: integer); external; 

begin {main} 

fildes:=gopen(’/dev/tty’.OUTDEV,’hp262x\ INIT); 
if fildes = -1 then exit(-l); 

vdc_extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 
clip.rectangle(fildes,-20.0,105.0,0.1575,0.1825); 
mapping_mode(fildes,1); 

interior.style(fildes,INTJH0LL0W,1); 
rectangle(fildes,-20.0,0.1575,105.0,0.1825); 
rectangle(fildes,0.0,0.1600,100.0,0.1800); 

reset(data,’data’); 
while(not eof(data)) do 
begin 

readln(data,coords[i],coords [i+1]); 
i := i+2; 

end; 

polyline2d(fildes,coords,i div 2,0); 
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fildes := gclose(fildes); 


end. 

The results of this modification to the example program are shown in Figure 1-19. This 
drawing was made with example5p.p. 



Figure 1-19. Plotted Data 
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Labels 

Let us now label the drawing. We will use two fonts, different character paths, and 
different text alignments to show some of the capabilities of the system. 

The syntax to do this is: 

program main(input,output); 

$include ’/usr/include/starbase.pi.h’$ 
const 

array_size = 200; 


type 

array_type = array[0..array_size] of real; 


var 

fildes, i, j, length: integer; 
x, y: real; 
coords: array_type; 
data: text; 
number: string[80]; 

$include */usr/include/starbase.p2.h * $ 
procedure exit(result: integer); external; 

begin {main} 

fildes : =gopen(’/dev/tty * ,0UTDEV, ’hp262x’,INIT) ; 
if fildes = -1 then exit(-l); 

vdc.extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 
clip_rectangle(fildes,-20.0,105.0,0.1575,0.1825); 
mapping.mode(fildes,1); 

interior.style(fildes,INT_H0LL0W,1); 
rectangle(fildes,-20.0,0.1575,105.0,0.1825); 
rectangle(fildes,0.0,0.1600,100.0,0.1800); 

text_alignment(fildes,TA_CENTER,TA_T0P,0.0,0.0); 
character.height(fildes,0.001); 

text2d(fildes,50.0,0.1588,’Time (seconds)’,VDC.TEXT,0); 

character.path(fildes,PATH_D0WN); 
text.alignment(fildes,TA.CENTER,TA.HALF,0.0,0.0); 
text2d(fildes,-14.0,0.1700,’Voltage’,VDC_TEXT,0); 

text.font_index(fildes,2); 

character.path(fildes,PATH_RIGHT); 

text.alignment(fildes,TA.CENTER,TA.BOTTOM,0.0,0.0); 


80 An Introduction to Starbase Graphics 



text2d(fildes,50.0,0.1810,’VOLTAGE VARIANCE’,VDC_TEXT,0); 

reset(data,’data’); 
while(not eof(data)) do 
begin 

readln(data,coords[i],coords [i + 1]); 
i := i+2; 

end; 

polyline2d(fildes,coords,i div 2,0); 
fildes := gclose(fildes); 

end. 

Our example is now shown Figure 1-20. This program is stored in example6p.p. 



Figure 1-20. A Labeled Plot 
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Tic Marks 

We now need to add the numerated tic marks. This is done with two loops. We use 
strwrite to change the tic mark numbers into strings to be drawn as text. 

program main(input,output); 

$include ’/usr/include/starbase.pi.h’$ 

const 

array_size = 200; 

type 

array_type = array[0..array_size] of real; 


var 

fildes, i, j, length: integer; 

x, y: real; 

coords: array_type; 

data: text; 

number: string[80]; 

$include ’/usr/include/starbase.p2.h * $ 
procedure exit(result: integer); external; 

begin {main} 


text.alignment(fildes,TA.CENTER,TA_CONTIMUOUS_VERTICAL,0.0,1.2); 
character_height(fildes,0.0006); 

x : = 0.0; 

strwrite(number,1,length,trunc(x):1); 
text2d(fildes,x,0.1598.number,VDC_TEXT,0); 
for i:=1 to 10 do 
begin 

for j:=1 to 5 do 
begin 

move2d(fildes,x,0.1600); 
draw2d(fildes,x,0.1603); 
x := x + 2.0; 

end; 

move2d(fildes,x,0.1600); 
draw2d(fildes,x,0.1605); 
strwrite(number,1,length,trunc(x):1); 
text2d(fildes,x,0.1600,number,VDC_TEXT,0); 

end; 

text.alignment(fildes,TA_CONTINUOUS_HORIZONTAL,TA.HALF,1.2,0.0); 
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y := 0.1600; 

strwrite(number,1,length,y:0:4); 
text2d(fildes,0.0,y,number,VDC_TEXT,0); 
for i:=l to 8 do 
begin 

for j:=1 to 5 do 
begin 

move2d(fildes,0.0,y); 
draw2d(fildes,1.0,y); 
y : = y + 0.0005; 

end; 

move2d(fildes,0.0,y); 
draw2d(fildes,2.0,y); 
strwrite(number,1,length,y:0:4); 
ext2(fildes,0.0,y,number,VDC_TEXT,0); 

end; 



Figure 1-21. The Final Plot 
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The whole program 

program main(input,output); 

$include ’/usr/include/starbase.pi.h’$ 
const 

array_size = 200; 

type 

array_type = array[0..array_size] of real; 


var 

fildes, i, j, length: integer; 
x, y: real; 
coords: array_type; 
data: text; 
number: string[80]; 

$include */usr/include/starbase.p2.h’$ 
procedure exit(result: integer); external; 

begin {main} 

fildes:=gopen(’/dev/tty’,OUTDEV,’hp262x’,INIT); 
if fildes = -1 then exit(-l); 

vdc.extent(fildes,-20.0,0.1575,0.0,105.0,0.1825,0.0); 
clip_rectangle(fildes,-20.0,105.0,0.1575,0.1825); 
mapping_mode(fildes,1); 

interior_style(fildes,INT_H0LL0W,1); 
rectangle(fildes,-20.0,0.1575,105.0,0.1825); 
rectangle(fildes,0.0,0.1600,100.0,0.1800); 

text_alignment(fildes,TA_CENTER,TA_T0P,0.0,0.0); 
character_height(fildes,0.001); 

text2d(fildes,50.0,0.1588,’Time (seconds)’,VDC_TEXT,0); 

character_path(fildes,PATH_D0WN); 
text_alignment(fildes,TA.CENTER,TA_HALF,0.0,0.0); 
text2d(fildes,-14.0,0.1700,’Voltage’,VDC_TEXT,0); 

text_font_index(fildes,2); 
character_path(fildes,PATH_RIGHT); 
text.alignment(fildes,TA.CENTER,TA.BOTTOM,0.0,0.0); 
text2d(fildes,50.0,0.1810,’VOLTAGE VARIANCE’,VDC_TEXT,0) 

reset(data,’data’); 
while(not eof(data)) do 
begin 

readln(data,coords[i],coords[i+1]); 
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i := i+2; 

end; 

polyline2d(fildes,coords,i div 2,0); 

text.alignment(fildes,TA.CENTER,TA_C0NTINU0US_VERTICAL,0.0,1.2); 
character.height(fildes,0.0006); 

x := 0.0; 

strwrite(number,1,length,trunc(x):1); 
text2d(fildes,x,0.1598,number,VDC.TEXT,0); 
for i:=1 to 10 do 
begin 

for j:=1 to 5 do 
begin 

move2d(fildes,x,0.1600); 
draw2d(fildes, x, 0.1603) ; 
x := x + 2.0; 

end; 

move2d(fildes,x,0.1600); 
draw2d(fildes,x,0.1605) ; 
strwrite(number,1,length,trunc(x):1); 
text2d(fildes,x,0.1600,number,VDC_TEXT,0); 

end; 

text.alignment(fildes,TA_C0NTINU0US_H0RIZ0NTAL,TA.HALF,1.2,0.0); 

„ — /\ A AA a 

y . “ KJ . , 

strwrite(number,1,length,y:0:4); 
text2d(fildes,0.0,y,number,VDC.TEXT,0) ; 
for i:=l to 8 do 
begin 

for j:=1 to 5 do 
begin 

move2d(fildes,0.0,y); 
draw2d(fildes,1.0,y); 
y := y + 0.0005; 

end ; 

move2d(fildes,0.0,y); 
draw2d(fildes,2.0,y); 
strwrite(number,1,length,y:0:4); 
text2d(fildes,0.0,y,number,VDC.TEXT,0); 

end; 

fildes := gclose(fildes); 

end. 
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Working with Text 

Introduction 

This section provides several examples of how text can be manipulated with Starbase. 
To be complete, the Text Alignment subsection gives numerous examples of how text 
can be aligned with respect to the coordinate position specified in the text2d or text 3d 
procedures. 

The Starbase Library Procedures discussed in this section include: 

• Procedures to draw text: 

• text2d 

• text3d 

• append_text 

• detext 

• Procedures to specify character sizes: 

• character_expansion_factor 

• character height 

• character_width 

• Procedures to select different fonts and character sets: 

• designate_character_set 

• t ext _ font _ index 

• Procedures to specify character locations relative to other characters: 

• charaeter_slant 

• text_line_space 

• text_path 

• intra_character_space 

• text Jme_path 
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• text.orientation 

• text.alignment 

• text_precision 

• A Procedure to specify the method by which charcters and escape code sequences 
are interpreted: 

• character_switching_mode 


The Four Methods of Drawing Text 

• append, text - is used to add text to previously executed text 2d or text 3d procedures 
when the parameter more is specified as TRUE or not equal to 0. This procedure also 
draws text at the current pen position. 

C Syntax: 

void >append_text(fildes,string,xform,more); 
int fildes,xform.more; 
char *string; 

Fortran77 Syntax: 

subroutine append.text(fildes,string,xform,more) 
integer*4 fildes.xform,more 
character*(*) string 

Pascal Syntax: 

procedure append.text(fildes:integer;string:string255;xform.more: 
integer); 

• text2d - draws text at the specified 2-dimensional Virtual Device Coordinate (x,y) 
position. 

The syntax for is procedure is: 

C Syntax: 

void text2d(fildes,x,y,string,xform,more); 
int fildes.xform,more; 
float x,y; 
char *string; 
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Fortran77 Syntax: 

subroutine text2d(fildes,x,y,string,xform,more) 
integer*4 fildes.xform,more 
real x,y 

character*(*) string 


Pascal Syntax: 

procedure text2d(fildes,x,y:integer;string:string255;xform,more:integer); 

text3d - draws text at the specified 3-dimensional Vitrual Device Coordinate (x,y,z) 
position. 

The syntax for is procedure is: 

C Syntax: 

void text3d(fildes,x,y,z,string,xform,more); 
int fildes.xform,more; 
float x,y,z; 
char *string; 


Fortran77 Syntax: 

subroutine text3d(fildes,x,y,z,string,xform,more) 
integer*4 fildes,xform,more 
real x.y.z 

character*(*) string 

Pascal Syntax: 

procedure text3d(fildes,x,y,z:integer;string:string255;xform.more:integer); 

detext - draws text at the specified device coordinate (dcx,dcy) position. 

C Syntax: 

void detext(fildes.dcx.dcy,string); 
int fildes,dcx.dcy; 
char *string; 

Fortran77 Syntax: 

subroutine detext(fildes,dex,dey,string) 
integer*4 fildes,dex,dey 
character*(*) string 

Pascal Syntax: 

procedure detext(fildes,dex,dey:integer;string:string255); 
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Text Attributes and Defaults 

The following attributes are set using the values in /usr/lib/starbase/defaults. 

• ISO 8-bit Character Mode. 

• GO and G2 point to the US ASCII character set, font 1. This is the default active 
character set. 

• G1 and G3 point to the HPROMAN character set, font 1. 

When a graphics output device is opened with the gopen procedure, the following text 
defaults are in effect. 

• Character_Path is PATH.RIGHT. 

• Character_Slant is 0. 

• Text.alignment is TA_NO RM A L_HOR IZONTA L and 
TA_NORMAL_VERTICAL. 

• Text.colorjndex is 1. 

• Text Jine_path is PATH.DOWN. 

• Text_precision is STROKE.TEXT. 

• All other default values are machine-dependent. 

Except for detext which is not transformed, all text is transformed with one of three ma¬ 
trices described below. The transformation to be done is specified by the xf orm parameter 
of the text procedures. 

• If xf orm = 0, then the Font Transformation Matrix is pre-concatenated with the Vir¬ 
tual Device Coordinate (VDC) to Device Coordinate (DC) Transformation Matrix 
and used as the font to device coordinate transformation matrix. 

• If xform = 1, the Font Transformation Matrix is pre-concatenated to the transfor¬ 
mation matrix on the top of the matrix stack and the resulting matrix is used as 
the font to device coordinate transformation matrix. 

• If xform = 2, the transformation matrix on top of the matrix stack is used as the 
font to device coordinate transformation matrix. 

The text 2d and text3d procedures use the flag more to indicate when the text specified 
in the procedure is to be buffered. The append_text procedure is then used to append 
text to the buffer. 
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• If more = FALSE or 0, no more text is expected, and the text is sent to the specified 
device. 

• if more — TRUE or not equal to 0, more text is to follow and the text is buffered. The 
appencLtext procedure is used to append more text to a text2d or text3d buffer. 
This flag is cancelled and any buffered text is sent to the specified device if a text 2d 
or text 3d procedure is executed. 

Character sets are directories stored in /usr/lib/starbase/stroke. Fonts are stored in 
the character set directories. For example, the fixed-width, stroked USASCII font is the 
file named 1 and is located in: 

/usr/lib/starbase/stroke/usascii/1 


Template Programs 

The following programs may be used as templates for the example programs to follow. 
To emphasize the text procedures being discussed, only those procedures will be listed. 
These procedures, when added to the templates, will create the complete programs used 
to draw the examples shown. 

The gopen function opens an I/O path the the specified graphic device and returns and 
integer file descriptor used to identify that device until the path is closed with the gclose 
function. 

Mapping mode defines whether the mapping of the vdc extent to the viewport is isotropic 
(NONDISTQRTED) or anisotropic (DISTORTED). 
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A Template for C Programs 

This program is /user/lib/starbase/demos/textOc. c. The default file descriptor is as¬ 
signed to an HP 2623 or HP 2627 Graphics Terminal. In either case, the device is specified 
and and output device and is initialized. 

This program is stored as exampleOc.c in the /usr/lib/starbase/demos directory. 
#include <starbase.c.h> 

main(argc,argv) 

int argc; char *argv[]; 

{ 

int fildes; 

if (argc > 2) fildes=gopen(argv [1],OUTDEV,argv[2],INIT); 
else fildes=gopen("/dev/tty",OUTDEV,"hp262x",INIT); 
if (fildes == -1) exit(-l); 

/* Starbase Procedures Go Here */ 

gclose(fildes); 

> 

A Template for Fortran77 Programs 

This template is /user/lib/starbase/demos/ftemplate. f. This template will only work 
with an HP 2623 or HP 2627 Graphics Terminal. To use this template on another device, 
you must use the appropriate parameters shown bolded in the fildes line shown below. 

This program is stored as exampleOf. f in the /usr/lib/starbase/demos directory. 

include ’/usr/include/starbase.f1.h* 

program template 

character NULL 

parameter(NULL = char(O)) 

include ’/usr/include/starbase.f2.h * 

integer*4 fildes,status 

fildes = geopen(’/dev/tty’//NULL,OUTDEV, , hp262x *//NULL,INIT) 
if (fildes .eq. -1) stop 

C Starbase Procedures Go Here 

status = gclose(fildes) 
end 
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For example, to use the above template with an HP 98700 Device, the fildes line would 
look like this: 

fildes = geopen(’/dev/98700’//NULL,OUTDEV,’hp98700’//NULL,INIT) 

A Template for Pascal Programs 

This template is stored in the file /user/lib/starbase/demos/ptemplate .p. This template 
will only work with an HP 2623 or HP 2627 Graphics Terminal. To use this template 
on another device, you must use the appropriate parameters for the ones bolded in the 
fildes line shown below. 

This program is stored as exampleOp.p in the /usr/lib/starbase/demos directory, 
program main(input,output); 

$include ’/usr/include/starbase.pi.h 5 $ 
var 

fildes, status : integer; 

$include */usr/include/starbase.p2.h’$ 
procedure exit(result : integer);external; 
begin {main} 

fildes := gopen( */dev/tty \ OUTDEV , , hp262x\ INIT) ; 
if fildes = -1 then exit(-l); 

{ Starbase Procedures Go Here } 

status := gclose(fildes); 
end. 

For example, to use the above template with an HP 98700 Device, the fildes line would 
look like this: 

fildes := gopen(*/dev/98700*,OUTDEV,’hp98700*,INIT); 


Working with Text 93 



Default Text 

The data values which define the characters that make up the text are all transformed by 
an internally calculated matrix into Virtual Device Coordinate values. For a discussion 
of the coordinate systems used by Starbase, see section 1 of this manual. 

The following example shows what default text looks like. Both the append_text and 
text2d procedures are used. 

This example was created by the program textlc.c found in /usr/lib/starbase/demos. 

C Syntax 

mapping_mode(fiIdes.TRUE); 
move2d(fildes,0.10,0.10); 

append_text(fildes,"Append.text defaults to Current Pen Position.", 

VDC.TEXT,FALSE); 

text2d(fildes, 0.10,0.90," Default Text with ",VDC.TEXT,TRUE); 
append_text(fildes," Appended Text ",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call mapping_mode(fildes,1) 
call move2d(fildes,0.10,0.10) 

call append_text(fildes,’Append.text defaults to Current Pen Position.’ 
c //NULL, VDC.TEXT,FALSE) 

call text2d(fildes, 0.01,0.95, ’ Default Text with ’//NULL,VDC.TEXT,TRUE) 
call append.text(fildes,’ Appended Text ’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

mapping_mode(fildes,1) ; 
move2d(fildes,0.10,0.10); 

append_text(fildes,’Append.text defaults to Current Pen Position.’, 
VDC.TEXT,FALSE); 

text2d(fildes,0.01,0.95,’ Default Text with ’,VDC.TEXT.TRUE); 
append.text(fildes,’ Appended Text ’.VDC.TEXT,FALSE); 
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Larger Text 

The previous example shows how default text can be quite small. For larger and more 
readable text, use the character_height procedure. 

The fildes parameter identifies the output graphic device. The height parameter is a 
fraction of the Y-axis length for the Virtual Device Coordinate extent and specifies the 
character’s height. 

Changing character height may also change character width. The default ratio of char¬ 
acter height to character width is maintained at 1.0 unless changed with the charac- 
ter_expansion_factor procedure. Character width may also be changed with the char¬ 
acter .width procedure. 

Changing a character’s width does not change the character’s height. 

Our example will specify a character height of 0.05. This example was created by the 
program text2c. c found in /usr/lib/starbase/camos. 

C Syntax 

character.height(fildes ,0.05) ; 

Fortran77 Syntax 

call character.height(fildes ,0.05) 

Pascal Syntax 

character.height(fildes ,0.05); 
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Default Text with Rppended Text 


Rppend text defaults to Current Pen Position 

L_ 

Figure 2-2. Larger Text (text2c.e) 
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Larger Text Continued 

A better look at how character.height changes the size of text can be seen with 
the following example. The character width is automatically changed by charac- 
ter.expansion.factor as the height changes. This factor is the ratio of character height 
to character width. The default ratio is 1.00, so the higher the character, the wider it 
becomes to keep the factor at 1.00. An example of how the character_expansion_f actor 
procedure works is presented later in the section. 

This example was created by the program text3c.c found in /usr/lib/starbase/demos. 

C Syntax 

text2d(fildes,0.0,0.8," Default Character Height (0.02)",VDC_TEXT,FALSE); 
character.height(fildes,0.04); 

text2d(fildes,0.0,0.7," Character Height of 0.04",VDC_TEXT,FALSE); 
character.height(fildes,0.06); 

text2d(fildes,0.0,0.6," Character Height of 0.06",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call text2d(fildes.0.0,0.8,’ Default Character Height (0.02)’//NULL, 
c VDC.TEXT,FALSE) 

call character_height(fildes,0.07) 

call text2d(fildes,0.0,0.4.’ Character Height of 0.04’//NULL,VDC.TEXT, 
c FALSE) 

call character.height(fildes,0.06) 

call text2d(fildes,0.0,0.6,’ Character Height of 0.06’//NULL,VDC.TEXT, 
c FALSE) 
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Pascal Syntax 

text2d(fildes,0.0,0.8,’ Default Character Height (0.02)’,VDC_TEXT,FALSE); 
character_height(fildes,0.04); 

text2d(fildes,0.0,0.7,’ Character Height of 0.04’,VDC_TEXT,FALSE); 
character_height(fildes,0.06); 

text2d(fildes,0.0.0.6,’ Character Height of 0.06 *,VDC.TEXT,FALSE); 
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Text Precision 

Text precision is selected with the text .precision procedure. This procedure has two 
parameters, fildes and precision. The first parameter identifies the graphics output device 
that will have the precision specified in the second parameter. 

The second parameter can be one of the three following precisions: 

• STRING.TEXT - the device’s text capabilities are used. Hardware text generation, 
in general, provides only limited approximations to the specified text attributes. 

• CHARACTER.TEXT - currently the same as STROKE.TEXT. 

• STROKE.TEXT - causes the characters to be drawn at a higher precision that 
hardware text, but may be slow on some devices. This is the default text precision. 

Depending upon the device, the visual differences between the various text precisions 
may or may not be noticable. With STRING.TEXT, changes in an attribute may seem 
erratic. For example, if you are changing the slant of some test characters. As you 
change the angle of the slant, the text on your screen my not seem to change until some 
angle is reached, then the text on you screen will change markedly. This change is device 
dependent. 
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Wide and Narrow Characters 

Characters can be made wider without changing their height. This is done with the 
character_width procedure. 

This example was created by the program text4c.c found in /usr/lib/starbase/demos. 

C Syntax 

character.height(fildes,0.04); 

text2d(fildes,0.0,0.50," Default Width of 0.50",VDC_TEXT.FALSE); 
character_width(fildes,0.010) ; 

text2d(fildes,0.0.0.10," Character Width of 0.010".VDC_TEXT,FALSE); 
character_width(fildes,0.020); 

text2d(fildes,0.0,0.20," Character Width of 0.020",VDC_TEXT,FALSE); 
character_width(fildes,0.030) ; 

text2d(fildes,0.0,0.30," Character Width of 0.030",VDC_TEXT,FALSE); 
character_width(fildes,0.040); 

text2d(fildes,0.0,0.40," Character Width of 0.040",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call character_height(fildes,0.04) 

call text2d(fildes,0.0,0.50,’ Default Width of 0.50’//NULL,VDC_TEXT, 
c FALSE) 

call character.width(fildes,0.010) 

call text2d(fildes,0.0,0.10,’ Character Width of 0.010’//NULL,VDC.TEXT, 
c FALSE) 

call character_width(fildes,0.020) 

call text2d(fildes,0.0,0.20, ’ Character Width of 0.020’//NULL,VDC.TEXT, 
c FALSE) 

call character_width(fildes,0.030) 

call text2d(fildes,0.0,0.30, ’ Character Width of 0.030’//NULL,VDC.TEXT, 
c FALSE) 

call character_width(fildes,0.040) 

call text2d(fildes,0.0,0.40, ’ Character Width of 0.040 7/NULL,VDC.TEXT, 
c FALSE) 
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Pascal Syntax 

character_height(fildes,0.04); 

text2d(fildes,0.0,0.50,’ Default Width of 0.50’,VDC_TEXT,FALSE); 
character_width(fildes,0.010) ; 

text2d(fildes,0.0,0.10,’ Character Width of 0.010’,VDC_TEXT,FALSE); 
character_width(fildes,0.020); 

text2d(fildes,0.0,0.20,’ Character Width of 0.020’,VDC_TEXT,FALSE); 
character_width(fildes,0.030); 

text2d(fildes,0.0,0.30,’ Character Width of 0.030’,VDC_TEXT,FALSE); 
character_width(fildes,0.040); 

text2d(fildes,0.0,0.40,’ Character Width of 0.040’,VDC_TEXT,FALSE); 

r t 


Default Character Width 
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Figure 2-4. Wide and Narrow Characters (text4c.c) 
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Character Expansion Factor 

The character.expansion_factor and character.width procedures are interactive with 
one another. The procedure to be executed last supersedes the former. If the last 
procedure was character_expansion_factor, then the width is adjusted with respect to 
the height of the characters. If the last procedure was char act er.width, then the width 
is adjusted without respect to the character’s height. 

This example was created by the program text5c.c found in /usr/lib/starbase/demos. 

C Syntax 

character.height(fildes,0.04); 
character.expansion.factor(fildes,0.75); 

text2d(fildes,0.05,0.80,"Character expansion factor 0.75".VDC.TEXT,FALSE); 
character_width(fildes,0.03); 

text2d(fildes,0.05,0.70,"Character Width of 0.03",VDC.TEXT,FALSE); 

character.width(fildes,0.040); 
character.expansion.factor(fildes,0.75); 

text2d(fildes,0.05,0.60,"Character expansion factor 0.75".VDC.TEXT,FALSE); 
text2d(fildes,0.05,0.55,"superseding width change".VDC.TEXT.FALSE); 

character.expansion.!'actor (t ildes ,1.5); 
character_width(fildes,0.030); 

text2d(fildes,0.05,0.40,"Character Width of 0.030".VDC.TEXT.FALSE); 
text2d(fildes,0.05,0.35,"superseding expansion change".VDC.TEXT,FALSE); 

Fortran77 Syntax 

call character.height(fildes,0.04) 

call character.expansion.factor(fildes,0.75) 

call text2d(fildes,0.05,0.80,’Character expansion factor 0.75’//NULL, 
c VDC.TEXT,FALSE) 

call character.width(fildes,0.03) 

call text2d(fildes,0.05,0.70,’Character Width of 0.03’//NULL,VDC.TEXT, 
c FALSE) 

call character_width(fildes,0.040) 

call character.expansion.factor(fildes,0.75) 

call text2d(fildes,0.05,0.60,’Character expansion factor 0.75’//NULL, 
c VDC.TEXT,FALSE) 

call text2d(fildes,0.05,0.55,’superseding width change’//NULL,VDC.TEXT, 
c FALSE) 
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call character_expansion_factor(fildes,1.5) 
call character.width(fildes,0.030) 

call text2d(fildes,0.05,0.40,’Character Width of 0.030’//NULL,VDC.TEXT, 
c FALSE) 

call text2d(fildes,0.05,0.35,’superseding expansion change’//NULL, 
c VDC.TEXT,FALSE) 

Pascal Syntax 

character_height(fildes,0.04); 
character_expansion_factor(fildes,0.75); 

text2d(fildes,0.05,0.80,’Character expansion factor 0.75’,VDC.TEXT,FALSE) 
character_width(fildes,0.03); 

text2d(fildes,0.05,0.70,’Character Width of 0.03’.VDC.TEXT,FALSE); 

character_width(fildes,0.040); 
character.expansion.factor(fildes,0.75); 

text2d(fildes,0.05,0.60,’Character expansion factor 0.75’.VDC.TEXT,FALSE) 
text2d(fildes,0.05,0.55,’superseding width change’.VDC.TEXT,FALSE); 

character.expansion.factor(fildes,1.5); 
character_width(fildes,0.030); 

text2d(fildes,0.05,0.40,’Character Width of 0.030’,VDC.TEXT,FALSE); 
text2d(fildes,0.05,0.35,’superseding expansion change’,VDC.TEXT,FALSE); 
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Intra Character Space 

This procedure defines the space (distance) between character cells. This distance is a 
fraction of character height. 

This example was created by the program text6c.c found in /usr/lib/starbase/demos. 

C Syntax 

character_height(fildes,0.04); 

text2d(fildes,0.0,0.0,"Default space of 0.0",VDC_TEXT,FALSE); 
intra_character_space(fildes,0.2); 

text2d(fildes,0.0,0.2,"Character space of .2",VDC.TEXT,FALSE); 
intra_character_space(fildes,0.4); 

text2d(fildes,0.0,0.4,"Character space of .4",VDC.TEXT,FALSE); 
intra_character_space(fildes,0.6); 

text2d(fildes,0.0,0.6,"Character space of .6",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call character_height(fildes,0.04) 

call text2d(fildes,0.0,0.0,’Default space of 0.0'//NULL,VDC.TEXT, 
c FALSE) 

call intra_character_space(fildes,0.2) 

call text2d(fildes,0.0,0.2,’Character space of .2’//NULL,VDC.TEXT,FALSE) 
call intra_character_space(fildes,0.4) 

call text2d(fildes,0.0,0.4,’Character space of .4’//NULL,VDC.TEXT,FALSE) 
call intra_character_space(fildes,0.6) 

call text2d(fildes,0.0,0.6,’Character space of .6’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

character_height(fildes,0.04) ; 

text2d(fildes,0.0,0.0,’Default space of 0.0’,VDC_TEXT,FALSE); 
intra_character_space(fildes,0.2); 

text2d(fildes,0.0,0.2,’Character space of .2’,VDC_TEXT,FALSE); 
intra_character_space(fildes,0.4); 

text2d(fildes,0.0,0.4,’Character space of .4’,VDC_TEXT,FALSE) ; 
intra_character_space(fildes,0.6); 

text2d(fildes,0.0,0.6,’Character space of .6’,VDC_TEXT,FALSE); 
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Character Slant 

You can alter the appearance of your text by changing the slant of its characters, Larger 
characters are shown for better visual clarity. 

This example was created by the program text7c.c found in /usr/lib/starbase/demos. 

C Syntax 

character^height(fildes,0.04); 
character.slant(fildes,0.0); 

text2d(fildes,0.0,0.15," Slant of 0, default",VDC_TEXT,FALSE); 
character_slant(fildes,.268); 

text2d(fildes,0.0,0.25," Slant of 0.268 or 15 degrees",VDC_TEXT.FALSE); 
character_slant(fildes,0.577); 

text2d(fildes,0.0,0.35," Slant of 0.577 or 30 degrees",VDC_TEXT.FALSE); 
character_slant(fildes,1.0); 

text2d(fildes,0.0,0.45," Slant of 1.00 or 45 degrees",VDC_TEXT,FALSE); 
character_slant(fildes,1.73); 

text2d(fildes,0.0,0.55," Slant of 1.73 or 60 degrees ",VDC_TEXT.FALSE); 
character_slant(fildes,3.73); 

text2(fildes,0.0,0.65," Slant of 3.73 or 75 degrees ",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call character ..height (f ildes, 0.04) 
call character_slant(fildes,0.0) 

call text2d(fildes,0.0,0.15,* Slant of 0, default’//NULL,VDC_TEXT,FALSE) 
call character_slant(fildes,.268) 

call text2d(fildes,0.0,0.25,’ Slant of 0.268 or 15 degrees’//NULL, 
c VDC.TEXT,FALSE) 

call character_slant(fildes,0.577) 

call text2d(fildes,0.0,0.35,’ Slant of 0.577 or 30 degrees’//NULL, 
c VDC.TEXT,FALSE) 

call character_slant(fildes,1.0) 

call text2d(fildes,0.0,0.45,’ Slant of 1.00 or 45 degrees’//NULL, 
c VDCLTEXT,FALSE) 
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call character_slant(fildes,1.73) 

call text2d(fildes,0.0,0.55,’ Slant of 1.73 or 60 degrees ’//NULL, 
c VDC_TEXT,FALSE) 

call character_slant(fildes,3.73) 

call text2d(fildes,0.0,0.65,’ Slant of 3.73 or 75 degrees ’//NULL, 
c VDC.TEXT,FALSE) 

Pascal Syntax 

character_height(fildes,0.04); 
character_slant(fildes,0.0) ; 

text2d(fildes,0.0,0.15,’ Slant of 0, default’,VDC_TEXT,FALSE); 
character_slant(fildes,.268); 

text2d(fildes,0.0,0.25,’ Slant of 0.268 or 15 degrees’,VDC_TEXT,FALSE); 
character_slant(fildes,0.577) ; 

text2d(fildes,0.0,0.35,’ Slant of 0.577 or 30 degrees’,VDC.TEXT,FALSE); 
character.slant(fildes,1.0); 

text2d(fildes,0.0,0.45,’ Slant of 1.00 or 45 degrees’,VDC_TEXT,FALSE); 
character_slant(fildes,1.73); 

text2d(fildes,0.0,0.55,’ Slant of 1.73 or 60 degrees ’,VDC_TEXT,FALSE); 
character^slant(fildes,3.73); 

text2d(fildes,0.0,0.65,’ Slant of 3.73 or 75 degrees ’,VDC_TEXT.FALSE); 
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Figure 2-7. Character Slant (text7c.c) 
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Text Path 

This procedure defines where the next character of a string is to be placed with respect 
to the currently drawn character. The second and following characters can be drawn in 
the following directions: 

• PATH.RIGHT 

• PATH_LEFT 

• PATH.UP 

• PATH.DOWN 

The resulting text is aligned according to the assignment made by the text.alignment pro¬ 
cedure. The default is TA_NORMAL_HORIZONTAL and TA.NORMAL.VERTICAL. 

This example was created by the program text8c. c found in /usr/lib/starbase/demos. 

C Syntax 

character_height(fildes,0.04); 
text2d(fildes.0.55.0.55,"Path right"); 
text_path(fildes,PATH_LEFT); 

text2d(fildes,0.45,0.55."Path left",VDC.TEXT,FALSE); 
text_path(fildes,PATH_UP); 

text2d(fildes,0.50,0.65,"Path up",VDC_TEXT,FALSE); 
text_path(fildes,PATH.DOWN); 

text2d(fildes,0.50,0.45,"Path down",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call character_height(fildes,0.04) 

call text2d(fildes,0.55,0.55,’Path right’//NULL,VDC.TEXT,FALSE) 
call text_path(fildes,PATH_LEFT) 

call text2d(fildes,0.45,0.55,’Path left’//NULL,VDC_TEXT,FALSE) 
call text_path(fildes,PATH_UP) 

call text2d(fildes,0.50,0.65,’Path up’//NULL,VDC_TEXT,FALSE) 
call text_path(fildes,PATH.DOWN) 

call text2d(fildes,0.50,0.45,’Path down’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

character_height(fildes,0.04); 
text2d(fildes,0.55,0.55,’Path right’); 
text_path(fildes,PATH_LEFT); 

text2d(fildes,0.45,0.55,’Path left’,VDC.TEXT,FALSE); 
text_path(fildes,PATH.UP); 

text2d(fildes,0.50,0.65,’Path up’.VDC.TEXT,FALSE); 
text_path(fildes,PATH.DOWN); 

text2d(fildes,0.50,0.45,’Path down’,VDC.TEXT,FALSE); 
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Text Line Path 

The following program shows how the text_line_path procedure works. This procedure 
defines the position of text following a line feed. Possible positions are: 

• PATH_RIGHT - Moves text one character width right. 

• PATH.LEFT - Moves text one character width left. 

• PATH.UP - Moves text one character height up. 

• PATH.DOWN - Moves text one character height down. 

This example was created by the program text9c.c found in /usr/lib/starbase/demos. 

C Syntax 

character.height(fildes,0.04); 
text_line_path(fildes, PATHJUGHT) ; 

text2d(fildes,0.3,0.4."Text with\n PATH_RIGHT",VDC_TEXT,FALSE); 
text_line_path(fildes,PATH_LEFT); 

text2d(fildes,0.3,0.5."Text with\n PATH_LEFT",VDC_TEXT,FALSE); 
text_line_path(fildes,PATH_UP); 

text2d(fildes,0.3,0.6,"Text with\n PATH_UP",VDC_TEXT,FALSE); 
text_line_path(fildes,PATH_D0WN); 

text2d(fildes,0.3,0.7,"Text with\n PATH.DOWN",VDC_TEXT,FALSE) ; 

Fortran77 Syntax 

Not Supported on Series 500 
call character_height(fildes,0.04); 
call text_line_path(fildes,PATH_RIGHT); 

call text2d(fildes,0.3,0.4,’Text with\n PATH.RIGHT’//NULL,VDC.TEXT,FALSE); 
call text_line_path(fildes,PATH_LEFT); 

call text2d(fildes,0.3,0.5,’Text with\n PATH_LEFT'//NULL,VDC.TEXT,FALSE); 
call text_line_path(fildes.PATHJJP); 

call text2d(fildes,0.3,0.6,’Text with\n PATH_UP*//NULL,VDC_TEXT,FALSE); 
call text_line_path(fildes,PATH_D0WN); 

call text2d(fildes,0.3,0.7,’Text with\n PATH.DOWN’//NULL,VDC.TEXT,FALSE); 
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Pascal Syntax 

character_height(fildes.O.04); 
text_line_path(fildes,PATH_RIGHT); 

text2d(fildes.O.3,0.4,’Text with’#10’ PATH.RIGHT’,VDC_TEXT,FALSE); 
text_line_path(fildes,PATH_LEFT); 

text2d(fildes.O.3,0.5,’Text with’#10’ PATH.LEFT’,VDC_TEXT,FALSE); 
text_line_path(fildes,PATH_UP); 

text2d(fildes,0.3,0.6,’Text with’#10’ PATH.UP’,VDC_TEXT,FALSE); 


text_line_path(fildes,PATH_DOWN); 

text2d(fildes.O.3,0.7,’Text with’#10’ PATH_DOWN’,VDC_TEXT,FALSE); 
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Figure 2-9. Text Line Path (text9c.c) 
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Text Orientation 

Text orientation is specified by two vectors. The up vector provides the up component 
of all vertical strokes that draw the text. The base vector provides the the horizontal 
component of all horizontal strokes that are used to draw the text. 

The procedure parameters are: 

• hides - identifies the device the procedure is accessing. 

• up_x, up_y - the x and y components of the up vector. 

• base_x, base_y - the x and y components of the base vector. 

This example was created by the program textlOc.c found in /usr/lib/starbase/demos. 

C Syntax 

character_height(fildes,0.04); 

text2d(fildes,0.0,0.0,"Default text",VDC_TEXT,FALSE); 
text_orientation(fildes,0.25,1.00,1.0,0.0); 

text2d(fildes,0.0,0.1,"Up vector now 0.25,1.0.",VDC_TEXT,FALSE); 
text orientation(fildes,0.50,1.00,1.0,0.0); 

text2d(fildes,0.0,0.2,"Up vector now 0.50,1.0.",VDC_TEXT,FALSE); 
text.orientation(fildes,0.75,1.00,1.0,0.0); 

text2(fildes,0.0,0.3,"Up vector now 0.75,1.0.",VDC_TEXT,FALSE); 
text_orientation(fildes,0.00,1.00,1.00,0.25); 

text2d(fildes,0.0,0.4,"Base vector now 1.00,0.25.",VDC_TEXT,FALSE); 
text_orientation(fildes,0.00,1.00,1.00,0.5); 

text2d(fildes,0.0,0.5,"Base vector now 1.00,0.50.»,VDC_TEXT,FALSE); 
text.orientation(fildes,0.00,1.00,1.00,0.75); 

text2d(fildes,0.0,0.6,"Base vector now 1.00,0.75.",VDC_TEXT,FALSE); 
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Fortran77 Syntax 

call character_height(fildes,0.04) 

call text2d(fildes,0.0,0.0,’Default text is shown here.’//NULL,VDC_TEXT, 
c FALSE) 

call text_orientation(fildes,0.25,1.00,1.0,0.0) 

call text2d(fildes,0.0,0.1,’Up vector now 0.25,1.0.’//NULL,VDC_TEXT, 
c FALSE) 

call text_orientation(fildes,0.50,1.00,1.0,0.0) 

call text2d(iildes,0.0,0.2,’Up vector now 0.50,1.0.’//NULL,VDC_TEXT, 
c FALSE) 

call text_orientation(fildes,0.75,1.00,1.0,0.0) 

call text2d(fildes,0.0,0.3,’Up vector now 0.75,1.0.’//NULL,VDC_TEXT, 
c FALSE) 

call text_orientation(fildes,0.00,1.00,1.00,0.25) 

call text2d(fildes,0.0,0.4,'Base vector now 1.00,0.25.’//NULL,VDC.TEXT, 
c FALSE) 

call text_orientation(fildes,0.00,1.00,1.00,0.5) 

call text2d(fildes,0.0,0.5,’Base vector now 1.00,0.50.’//NULL,VDC.TEXT, 
c FALSE) 

call text_orientation(fildes,0.00,1.00,1.00,0.75) 

call text2d(fildes,0.0,0.6,’Base vector now 1.00,0,75.’//NULL,VDC.TEXT, 
c FALSE) 

Pascal Syntax 

character_height(fildes,0.04); 

text2d(fildes,0.0,0.0,’Default text is shown here.’.VDC.TEXT,FALSE); 

text_orientation(fildes,0.25,1.00,1.0,0.0); 

text2d(fildes,0.0,0.1,’Up vector now 0.25,1.0.’,VDC.TEXT,FALSE); 

text.orientation(fildes,0.50,1.00,1.0,0.0); 

text2d(fildes,0.0,0.2,’Up vector now 0.50,1.0.’.VDC.TEXT,FALSE); 

text.orientation(fildes,0.75,1.00,1.0,0.0); 

text2d(fildes,0.0,0.3,’Up vector now 0.75,1.0.’.VDC.TEXT,FALSE); 
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text_orientation(fildes,0.00,1.00,1.00,0.25); 

text2d(fildes,0.0,0.4,’Base vector now 1.00,0.25 . ’ , VDCJTEXT, FALSE) ; 
text_orientation(fildes,0.00,1.00,1.00,0.5); 

text2d(fildes,0.0,0.5,’Base vector now 1.00,0.50.*,VDC.TEXT,FALSE); 
text_orientation(fildes,0.00,1.00,1.00,0.75); 

text2d(fildes,0.0,0.6,’Base vector now 1.00,0.75.’,VDC_TEXT,FALSE); 
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Text Line Space 

This procedure defines the distance between lines when a line feed is executed in a string 
of text. The following example shows several lines with different line space distances. 

This work was drawn using textile.c found in /dev/starbase/demos. 
character_height(fildes,0.04); 

text2d(fildes,0.0,0.9,"Text with normal\ntext line space",VDC_TEXT,FALSE); 
text_line_space(fildes,0.50); 

text2d(fildes,0.0,0.7,"Text with 0.50\ntext line space",VDC_TEXT,FALSE); 
text_line_space(fildes,1.50); 

text2d(fildes,0.0,0.5,"Text with 1.50\ntext line space",VDC_TEXT,FALSE); 
text_line_space(fildes,2.00); 

text2d(fildes,0.0,0.3,"Text with 2.00\ntext line space",VDC_TEXT,FALSE); 

Fortran77 Syntax 

Not Supported on Series 500 

call character_height(fildes,0.04) 

call text2d(fildes,0.0,0.9,’Text with normal text line space *,VDC_TEXT, 
c FALSE) 

call text__line_space(fildes ,0.50) 

call text2d(fildes,0.0,0.7,’Text with 0.50\ntext line space *,VDC_TEXT, 
c FALSE) 

call text__line_space(f ildes,1.50) 

call text2d(fildes,0.0,0.5,’Text with 1.50\ntext line space *.VDCLTEXT, 
c FALSE) 

call text_line_space(fildes,2.00) 

call text2d(fildes,0.0,0.3,’Text with 2.00\ntext line space’,VDC_TEXT, 
c FALSE) 
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Pascal Syntax 

character_height(fildes,0.04); 

text2d(fildes,0.0,0.9,’Text with normal’#10’text line space’,VDC_TEXT,FALSE); 
text_line_space(fildes,0.50); 

text2d(fildes,0.0,0.7,’Text with 0.50’#10’text line space’,VDC_TEXT,FALSE); 
text_line_space(fildes,1.50); 

text2d(fildes,0.0,0.5,’Text with 1.50’#10’text line space’,VDC_TEXT,FALSE); 


text_line_space(fildes,2.00); 

text2d(fildes,0.0,0.3,’Text with 2.00’#10’text line space’,VDC_TEXT,FALSE); 
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Text Alignment 

This procedure controls text alignment and has the following parameters: 

• hides - as usual, this identifies the target device. 

• h.select - this is the horizontal centering and can be one of the following: 

1. TA.LEFT 

2. TA.CENTER 

3. TA_RIGHT 

4. TA_CONTINUOUS_HORIZONTAL 

5. TA_NORMAL_HORIZONTAL 

• v.select - this is the vertical centering and can be one of the following: 

1. TA.TOP 

2. TA.CAP 

3. TA.HALF 

4. TA.BASE 

5. TA.BOTTOM 

6. TA_CONTINUOUS_VERTICAL 

7. TA_NORMAL_VERTICAL 

• horizontal - the fraction of the face of the text extent box which appears to the neg¬ 
ative side of the up vector, (only used with TA_CONTINUOUS_HORIZONTAL) 

• vertical - the fraction of the face of the text extent box which appears on the positive 
side of the base vector, (only used with TA.CONTINUOUS.VERTICAL) 
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Figure 2-12. A Character 

In the examples that follow, lines will be drawn to intersect the location specified for the 
text to be drawn. The text will consist of the string ABC using large characters. 
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Text alignment - TA_LEFT 

With this text alignment, the lower left point of the first character in the text extent box 
is on the point specified in the text 2d or text3d statement. 

This example was created by the program textile.e found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA.LEFT",VDCJTEXT,FALSE); 

text2d(fildes,0.55,0.85,"With TA_NORMAL_VERTICAL",VDC.TEXT,FALSE); 

character_height(fildes,0.18); 

text.alignment(fildes,TA^LEFT,TA_N0RMAL_VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call mO¥e2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character_height(fildes,0.04) 

call text2d(fildes,0.55,0.90,*TA_LEFT*//NULL,VDC_TEXT,FALSE) 

call text2d(fildes,0.55,0.85,’With TA.NOMALJVERTICAL’//NULL,VDC_TEXT,FALSE) 

call character_height(fildes,0.18) 

call text.alignment(fildes,TA.LEFT,TA.NORMAL.VERTICAL,0.0,0.0) 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC_TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,*TA_LEFT’,VDC_TEXT,FALSE); 

text2d(fildes,0.55,0.85,’With TA_NORMAL_VERTICAL’,VDC_TEXT,FALSE); 

character_height(fildes,0.2); 

text_alignment(fildes.TA_LEFT,TA_NORMAL_VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT,FALSE); 
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Text alignment - TA_CENTER 

The text extent box is centered at the point specified in the text 2d or text 3d procedure 
call. 


This example was created by the program text13c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character.height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA.CENTER",VDC.TEXT,FALSE); 

text2d(fildes,0.55,0.85,”With TA.NORMAL.VERTICAL",VDC.TEXT,FALSE); 

character.height(fildes,0.18); 

text.alignment(fildes,TA.CENTER,TA.NORMAL.VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character.height(fildes,0.04) 

call text2d(fildes,0.55,0.90,*TA.CENTER’//NULL,VDC.TEXT,FALSE) 

call text2d(fildes,0.55,0.85,’With TA.NOMAL.VERTICAL’//NULL,VDC.TEXT,FALSE) 

call character.height(fildes,0.18) 

call text.alignment(fildes,TA.CENTER,TA.NORMAL.VERTICAL,0.0,0.0) 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5.1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA_CENTER’,VDC.TEXT,FALSE); 

text2d(fildes,0.55,0.85,’With TA_NORMAL_VERTICAL*,VDC_TEXT,FALSE); 

character_height(fildes,0.2); 

text.alignment(fildes,TA.CENTER,TA_NORMAL_VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC.TEXT,FALSE); 
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Text alignment - TA_RIGHT 

The intersection of the character base vector and the right edge of the most right character 
is places at the the point specified in the text2d or text 3d procedure call. 

This example was created by the program textl4c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,10,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA_RIGHT",VDC.TEXT,FALSE); 

text2d(fildes,0.55,0.85,"With TA_N0RMAL_VERTICAL",VDC.TEXT,FALSE); 

character_height(fildes,0.18); 

text.alignment(fildes,TA.RIGHT,TA_N0RMAL_VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character.height(fildes,0.04) 

call text2d(fildes,0.55,0.90,’TA.RIGHT’//NULL,VDC.TEXT,FALSE) 

call text2d(fildes,0.55,0.85,’With TA_NOMAL_VERTICAL’//NULL,VDC.TEXT,FALSE) 

call character.height(fildes,0.18) 

call text.alignment(fildes,TA.RIGHT,TA.NORMAL.VERTICAL,0.0,0.0) 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5) ; 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0) ; 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA.RIGHT’,VDCLTEXT,FALSE); 

text2d(fildes,0.55,0.85,’With TA_NORMAL_VERTICAL’,VDC_TEXT,FALSE); 

character_height(fildes,0.2); 

text_alignment(fildes,TA_RIGHT,TA_NORMAL_VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.6,’ABC’,VDC_TEXT,FALSE); 
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Text alignment - 

TACONTINUOUSHORIZONTAL #1 

With this procedure, the parameter horizontal is used to allow the specification of what 
percentage (as a fraction) of the the text extent box is to the positive side of the point 
specified in the text2d or text3d procedure. This percentage can be a real number greater 
than 1.00. For the first example, a percentage fraction of 0.20 is used. 

This example was created by the program textlBc.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character.height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA.CONTINUOUS.HORIZONTAL",VDC.TEXT,FALSE); 
text2d(fildes,0.55,0.85,"With horizontal = 0.20",VDC.TEXT,FALSE); 
text2d(fildes,0.55,0.80,"and TA.N0RMAL.VERTICAL",VDC.TEXT,FALSE); 

character.height(fildes,0.18); 

text.alignment(fildes,TA.C0NTINU0US.H0RIZ0NTAL,TA.NORMAL.VERTICAL,0.2,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character.height(fildes,0.04) 

call text2d(fildes,0.55,0.90,’TA.CONTINUOUS.HORIZONTAL’//NULL,0,0) 
call text2d(fildes,0.55,0.85,’With horizontal = 0.207/NULL,0,0) 
call text2d(fildes,0.55,0.80,’and TA.NOMAL.VERTICAL7/NULL,0,0) 

call character.height(fildes,0.18) 

call text.alignment(fildes,TA.CONTINUOUS.HORIZONTAL,TA.NORMAL.VERTICAL,0.2,0.0) 
call text2d(fildes,0.5,0.5,’ABC7/NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0) ; 
draw2d(fildes,0.5,1.0); 

character_height(iildes,0.04); 

text2d(f ildes, 0.55,0.90, ’TA_C0NTINU0US_H0RIZ0NTAL-’ ,VDC_TEXT , FALSE) ; 
text2d(fildes,0.55,0.85,’With horizontal = 0.20’,VDC_TEXT.FALSE); 
text2d(fildes,0.55,0.80,’and TA_NORMAL_VERTICAL’,VDC_TEXT,FALSE); 

character_height(fildes,0.2); 

text.alignment(fiIdes,TA_C0NTINU0US_H0RIZ0NTAL,TA_NORMAL_VERTICAL,0.2,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT,FALSE); 
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Text alignment - 

TA_CONTINUOUS_HORIZONTAL #2 

For this example, a horizontal value of 0.7 was used. 

This example was created by the program textl6c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA_C0NTINU0US_H0RIZ0NTAL",VDC.TEXT,FALSE); 
text2d(fildes,0.55,0.85,"With horizontal = 0.7",VDC.TEXT.FALSE); 
text2d(fildes,0.55,0.80,"and TA_NORMAL_VERTICAL",VDC_TEXT,FALSE); 

character_height(fildes,0.2); 

text.alignment(fildes,TA_C0NTINU0US_H0RIZ0NTAL,TA.NORMAL.VERTICAL,0.7,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character.height(fildes,0.04) 

call text2d(fildes,0.55,0.90,’TA.CONTINUOUS.HORIZONTAL’//NULL,0,0) 
call text2d(fildes,0.55,0.85,’With horizontal = 0.7//NULL,0,0) 
call text2d(fildes,0.55,0.80,’and TA_NORMAL_VERTICAL//NULL,0,0) 

call character.height(fildes,0.2) 

call text_alignment(fildes,TA_C0NTINU0US_H0RIZ0NTAL,TA_NORMAL_VERTICAL,0.7,0.0); 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5) ; 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0) ; 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA_CONTINUOUS_HORIZONTAL *,VDC_TEXT,FALSE); 
text2d(fildes,0.55,0.85,’with horizontal = 0.7’,VDC_TEXT.FALSE); 
text2d(fildes,0.55,0.80,’and TA_NORMAL_VERTICAL’,VDC_TEXT,FALSE); 

character_height(fildes,0.2); 

text.alignment(fildes,TA_CONTINUOUS_HORIZONTAL,TA_NORMAL_VERTICAL.0.7,0.0); 
text2d(fildes,0.5.0.5,’ABC’,VDC.TEXT,FALSE); 



Figure 2-17. Text Alignment - TA_CONTINUOUS_HORIZONTAL Example #2 
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Text alignment - TA_NORMAL_HORIZONTAL 

This example was created by the program text!7c.c found in /usr/lib/starbase/demos. 


C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5) ; 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04 ); 

text2d(fildes,0.55,0.90,"TA_N0RMAL_H0RIZ0NTAL".VDC.TEXT,FALSE); 
text2d(fildes,0.55,0.85,"With TA_N0RMAL_VERTICAL",VDC.TEXT,FALSE); 

character_height(fildes,0.2); 

text_alignment(fildes,TA.NORMAL.HORIZONTAL,TA.NORMAL.VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 


call character.height(fildes,0.04) 

call text2d(fildes,0.55,0.90,’TA_N0RMAL_H0RIZ0NTAL’//NULL,VDC.TEXT, 
c FALSE) 

call text2d(fildes,0.55,0.85,’With TA.NORMAL.VERTICAL,VDC.TEXT,FALSE) 
call character.height(fildes,0.2) 

call text.alignment(fildes,TA.NORMAL.HORIZONTAL,TA.NORMAL.VERTICAL,0.0,0.0); 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA_N0RMAL_H0RIZ0NTAL’,VDC_TEXT,FALSE); 
text2d(fildes,0.55,0.85,’with TA_NORMAL_VERTICAL’,VDC_TEXT,FALSE); 

character.height(fildes,0.2); 

text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA_NORMAL_VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT.FALSE); 



Figure 2-18. Text Alignment - TA_NORMAL_HORIZONTAL (textl7c.c) 
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Text alignment - TA_TOP 

Depending upon how the character is defined in its cell, there is usually space between the 
top of the character (cap) and the top of the character cell (top). With this procedure, 
the intersection of the top of the text extent box and the right edge of the first character 
in the string is is aligned with the point specified in the text2d or text3d procedure call. 

This example was created by the program textl8c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA_T0P",VDC.TEXT,FALSE); 

text2d(fildes,0.55,0.85,"with TA_N0RMAL_H0RIZ0NTAL",VDC_TEXT,FALSE); 
character_height(fildes,0.2); 

text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA_T0P,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character_height(fildes,0.04) 

call text2d(fildes,0.55,0.90,’TA.TOP’//NULL,0,0) 

call text2d(fildes,0.55,0.85,’with TA_N0RMAL_H0RIZ0NTAL’//NULL,0,0) 
call character_height(fildes,0.18) 

call text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA.TOP,0.0,0.0) 
call text2d(fildes,0.5,0.5,’ABC’//NULL,0,0) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5) ; 
move2d(fildes,0.5,0.0); 
draw2d(fildes, 0.5,1.0); 

character.height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA_T0P’,VDC_TEXT,FALSE); 

text2d(fildes,0.55.0.85,’with TA_NORMAL_HORIZONTAL’,VDC_TEXT,FALSE); 
character_height(fildes,0.2); 

text.alignment(fildes,TA_NORMAL_HORIZONTAL,TA_TOP,0.0,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT,FALSE); 
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Text alignment - TA_CAP 

This alignment is the same at TA_TOP except that the CAP (top of the character) is used 
instead of the top of the character cell. 

This example was created by the program textl9c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA_CAP",VDC_TEXT,FALSE); 

text2d(fildes,0.55,0.85,"with TA_N0RMAL_H0RIZ0MTAL",VDC.TEXT,FALSE); 
character_height(fildes ,0.18) ; 

text_alignment(fildes,TA_N0RMAL.HORIZONTAL,TA_CAP,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character ..height (f ildes, 0.04) 

call text2d(fildes,0.55,0.90,’TA_CAP*//NULL,VDC_TEXT.FALSE) 

call text2d(fildes,0.55,0.85,’with TA_N0RMAL_H0RIZ0NTAL*,VDC_TEXT,FALSE) 

call character_height(fildes,0.2) 

call text.alignment(fildes,TA.NORMAL.HORIZONTAL,TA.CAP,0.0,0.0) 
call text2d(fildes,0.5,0.5,*ABC *//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA.CAP’,VDC_TEXT,FALSE); 

text2d(fildes,0.55,0.85,’with TA_N0RMAL_H0RIZ0NTAL’,VDC_TEXT,FALSE); 
character_height(fildes,0.2); 

text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA.CAP,0.0,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC.TEXT,FALSE); 



Figure 2-20. Text Alignment - TA_CAP (text!9c.c) 
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Text alignment - TA_HALF 

The position TA.HALF is located half way between the character cell cap and base. This 
location may or may not be the center of the drawing character. In this example, the 
two locations are not the same. 

This example was created by the program text20c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5) ; 
draw2d(fildes, 1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character.height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA_HALF",VDC_TEXT.FALSE); 

text2d(fildes,0.55,0.85,"with TA_N0RMAL_H0RIZ0NTAL",VDC.TEXT,FALSE); 
character_height(fildes,0.18); 

text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA_HALF,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character_height(fildes,0.04) 

call text2d(fildes,0.55,0.90,’TA.HALF’//NULL,VDC_TEXT,FALSE) 

call text2d(fildes,0.55,0.85,’with TA_N0RMAL_H0RIZ0NTAL’,VDC_TEXT,FALSE); 

call character_height(fildes,0.18) 

call text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA.HALF,0.0,0.0) 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character.height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA.HALF’,VDC_TEXT,FALSE); 

text2d(fildes,0.55,0.85,’with TA_N0RMAL_H0RIZ0NTAL’,VDC_TEXT,FALSE); 
character_height(fildes,0.18); 

text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA.HALF, 0.0,0.0) ; 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT.FALSE); 
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Text alignment - TAJBASE 

This example was created by the program text21c.c found in /usr/lib/starbase/demos. 


C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04) ; 

text2d(fildes,0.55,0.90."TA.BASE",VDC_TEXT,FALSE); 

text2d(fildes,0.55,0.85,"with TA_N0RMAL_H0RIZ0NTAL",VDC.TEXT,FALSE); 
character.height(fildes,0.18); 

text.alignment(fildes,TA_NORMAL_HORIZONTAL,TA.BASE,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC".VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character_height(fildes,0.04) 

call't ext2d(fildes,0.55,0.90,’TA_BASE’//NULL,VDC.TEXT,FALSE) 

call text2d(fildes,0.55,0.85,’with TA.NORMAL.HORIZONTAL’.VDC.TEXT.FALSE); 

call character.height(fildes,0.18) 

call text.alignment(fildes,TA.NORMAL.HORIZONTAL,TA.BASE,0.0,0.0) 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA_BASE *,VDC.TEXT,FALSE); 

text2d(fildes,0.55,0.85,’with TA_N0RMAL_H0RIZ0NTAL’,VDC.TEXT,FALSE); 
character_height(fildes,0.18); 

text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA.BASE,0.0,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT,FALSE); 



Figure 2-22. Text Alignment - TA.BASE (text21c.c) 
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Text alignment - TA_BOTTOM 

Depending upon how the character is defined in its cell, there is usually space between 
the bottom of the character (base) and the bottom of the character cell (bottom). With 
this procedure, the intersection of the bottom of the text extent box and the right edge 
of the first character in the string is is aligned with the point specified in the text 2d or 
text 3d procedure call. 

This example was created by the program text22c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,10,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character.height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA.BOTTOM",VDC.TEXT,FALSE); 

text2d(fildes,0.55,0.85,"with TA_N0RMAL_H0RIZ0NTAL",VDC_TEXT,FALSE); 

character_height(fildes,0.2); 

text_alignment(fildes,TA_LEFT,TA_B0TT0M,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character_height(fildes,0.04) 

call text2d(fildes,0.55,0.90,’TA.BOTTOM’//NULL,VDC.TEXT,FALSE) 

call text2d(fildes,0.55,0.85,’with TA.NORMAL.HORIZONTAL’//NULL,VDC.TEXT,FALSE); 

call character.height(fildes,0.2) 

call text.alignment(fildes,TA.LEFT,TA.BOTTOM,0.0,0.0) 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA.BOTTOM’,VDC.TEXT,FALSE); 

text2d(fildes,0.55,0.85,’with TA_NORMAL_HORIZONTAL’,VDC_TEXT,FALSE); 

character_height(fildes,0.2); 

text_alignment(fildes,TA_LEFT,TA_BOTTOM,0.0,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC.TEXT,FALSE); 
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Text alignment - 

TA_CONTINUOUS_VERTICAL Example #1 

With this procedure, the parameter vertical is used to allow the specification of what 
percentage (as a fraction) of the the text extent box is to below the point specified in 
the text2d or text3d procedure. This percentage can be a real number greater than 1.00. 
For the first example, a percentage fraction of 0.35 is used. 

This example was created by the program text23c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5) ; 
draw2d(fildes,1.0,0.5) ; 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,"TA_C0NTINU0US_VERTICAL".VDC.TEXT,FALSE); 
text2d(fildes,0.55,0.85,"With vertical = 0.35".VDC.TEXT,FALSE); 
text2d(fiIdes,0.55,0.80,"and TA.CONTINUOUS.HORINTOZAL",VDC.TEXT,FALSE); 

character_height(fildes,0.2); 

text.alignment(fildes,TA.LEFT,TA.C0NTINU0US.VERTICAL,0.0,0.35); 
text2d(fildes,0.5.0.5,"ABC",VDC.TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character.height(fildes,0.04) 

call text2d(fildes,0.55,0.90,’TA_C0NTINU0US_VERTICAL’//NULL,VDC.TEXT, 
c FALSE) 

call text2d(fildes,0.55,0.85,’With vertical = 0.35//NULL,VDC.TEXT,FALSE) 
call text2d(fildes,0.55,0.80,’and TA.C0NTINU0US.H0RINT0ZAL*//NULL,0,0); 

call character.height(fildes,0.18) 

call text.alignment(fildes,TA.LEFT,TA.CONTINUOUS.VERTICAL,0.0,0.35); 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA_C0NTINU0US_VERTICAL’,VDC_TEXT,FALSE); 
text2d(fildes,0.55,0.85,’with vertical = 0.35’,VDC_TEXT,FALSE); 
text2d(fildes,0.55,0.80,’and TA_C0NTINU0US_H0RINT0ZAL’,0,0); 

character_height(fildes,0,18); 

t ext.alignment(fildes,TA_LEFT,TA_CONTINUOUS_VERTICAL,0.0,0.35); 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT.FALSE); 
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Text alignment - 

TA_CONTINUOUS_VERTICAL Example #2 

As a second example, a vertical value of 0.75 is used. 

This example was created by the program text24c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

t ext2d(fildes,0.55,0.90,"TA_C0NTINU0US_VERTICAL",VDC_TEXT,FALSE); 
text2d(fildes,0.55,0.85,"With vertical = 0.75",VDC_TEXT,FALSE); 
text2d(fildes,0.55,0.80,"and TA_N0RMAL_H0RIZ0NTAL",VDC_TEXT,FALSE); 

character_height(fildes,0.18); 

text_alignment(fildes,TA_LEFT,TA_C0NTINU0US_VERTICAL,0.0,0.75); 
text2d(fildes,0.5,0.5,"ABC",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character.height(fildes,0.04) 

call text2d(fildes,0.55,0.90,*TA_C0NTINU0US_VERTICAL’//NULL,VDC.TEXT, 
c FALSE) 

call text2d(fildes,0.55,0.85,'With vertical = 0.75//NULL,0,0) 
call text2d(fildes,0.55,0.80,’and TA_N0RMAL_H0RIZ0NTAL’//NULL,0,0); 

call character.height(fildes,0.18) 

call text.alignment(fildes,TA.LEFT,TA_CONTINUOUS_VERTICAL,0.0,0.75); 
call text2d(fildes,0.5,0.5,’ABC’//NULL,0,0) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA_CONTINUOUS_VERTICAL’,VDC_TEXT,0); 
text2d(fildes,0.55,0.85,’with vertical = 0.75’,VDC_TEXT,0); 
text2d(fildes,0.55,0.80,’and TA_N0RMAL_H0RIZ0NTAL’,VDC_TEXT,0); 

character.height(fildes,0.18); 

text.alignment(fildes,TA.LEFT,TA_C0NTINU0US_VERTICAL,0.0,0.75); 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT,0); 



Working with Text 147 





Text alignment - TA_NORMAL_VERTICAL 

This example was created by the program text25c.c found in /usr/lib/starbase/demos. 

C Syntax 

move2d(fildes,0.0,0.5); 
draw2d(lildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90."TA_NORMAL_VERTICAL",VDC_TEXT,FALSE); 
text2d(fildes,0.55,0.85,"TA_N0RMAL_H0RIZ0NTAL",VDC.TEXT.FALSE); 

character_height(fildes,0.18); 

text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA.NORMAL.VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,"ABC",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call move2d(fildes,0.0,0.5) 
call draw2d(fildes,1.0,0.5) 
call move2d(fildes,0.5,0.0) 
call draw2d(fildes,0.5,1.0) 

call character_height(fildes,0.04) 

call text2d(fildes,0.55,0.90.*TA_N0RMAL_VERTICAL’//HULL,VDC.TEXT, 
c FALSE) 

call text2d(fildes,0.55,0.85,’TA_N0RMAL_H0RIZ0NTAL’//NULL,VDC_TEXT,FALSE) 
call character_height(fildes,0.18) 

call text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA.NORMAL.VERTICAL,0.0,0.0); 
call text2d(fildes,0.5,0.5,’ABC’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

move2d(fildes,0.0,0.5); 
draw2d(fildes,1.0,0.5); 
move2d(fildes,0.5,0.0); 
draw2d(fildes,0.5,1.0); 

character_height(fildes,0.04); 

text2d(fildes,0.55,0.90,’TA_NORMAL_VERTICAL’,VDC_TEXT,FALSE); 
text2d(fildes,0.55,0.85,’TA_N0RMAL_H0RIZ0NTAL’,VDC_TEXT,FALSE); 

character.height(fildes,0.2); 

text.alignment(fildes,TA_N0RMAL_H0RIZ0NTAL,TA_NORMAL_VERTICAL,0.0,0.0); 
text2d(fildes,0.5,0.5,’ABC’,VDC_TEXT,0); 
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Designate Character Set 

The following program shows how to select the various character sets. 

This example was created by the program text26c.c found in /usr/lib/starbase/demos. 

#include <starbase.c.h> 
main(argc,argv) 
int argc; 
char *argv[] ; 

{ 

int fildes,chset,gset; 
float x,y; 
char *c; 

static char *chsets[] = { 

"usascii", 

"hproman", 

"jisascii", 

"katakana" 

>; 

fildes = gopen("/dev/tty",OUTDEV,"hp262x",INIT); 
vdc_extent(fildes,0.0,0.0,0.0,13.0,9.0,0.0); 
clip_rectangle(fildes,0.0,13.0,0.0,9.0); 
character_height(fildes,1.0); 
for (chset=0; chset<=3; chset++) { 
for (gset=0; gset<=3; gset++) { 
designate_character_set(fildes,"",0); 
designate__character_set (fildes , "", 1) ; 
designate_character_set(fildes,"",2); 
designate_character_set(fildes,"",3); 
designate_character_set(fildes,chsets[chset] ,gset); 
set_pl_p2(fildes,FRACTIONAL,chset/4.0,gset/4.0, 

0.0,(chset+1.0)/4.0,(gset+1.0)/4.0,0.0); 

switch (gset) { 
case 0: 
c="\017"; 
break; 
case 1: 
c="\016"; 
break; 
case 2: 
c="\033n"; 
break; 
case 3: 
c="\033o"; 
break; 

> 

text2d(fildes,0.0,0.0,c,0,0); 

text2d(fildes, 1.0,1.0," !\"#$ 0 /,&’()*+",0,0) ; 


150 Working with Text 




text2d(fildes,1.0,20,",-./01234567",0,0); 
text2d(fildes,1.0,3.0,"89:;<=>?@ABC",0,0); 
text2d(fildes,l.0,4.0,"DEFGHIJKLMNO",0,0); 
text2d(fildes,1.0,5.0,"PQRSTUVWXYZ [",0,0); 
text2d(fildes,1.0,6.0,"\\]‘abcdefg",0,0); 
text2d(fildes,1.0,7.0,"hijklmnopqrs",0,0); 

text2d(f ildes, 1.0,8.0, "tuvwxyz{ I }~| height6pt width4pt depthOpt" ,0,0) 

> 

> 

gclose (fildes); 

> 



Figure 2-27. Character Sets 
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The following table shows the escape sequences needed to select a specific character set. 


shift function 

ISO 7 bit 

ISO 8 bit 

HP 8 bit 

Shift out 

so 

0/14 

- 

0/14 

Shift in 

SI 

0/15 

- 

0/15 

Locking shift zero 

LSO 

- 

00/15 

- 

Locking shift one 

LSI 

- 

00/14 

- 

Locking shift one right 

LS1R 

- 

esc 7/14 

- 

Locking shift two 

LS2 

esc 6/14 

esc 6/14 

- 

Locking shift two right 

LS2R 

- 

esc 7/13 

- 

Locking shift three 

LS3 

esc 6/15 

esc 6/15 

- 

Locking shift three right 

LS3 

- 

esc 7/12 

- 

Single shift two 

SS2 

esc 4/14* 

08/14 

- 

Single shift three 

SS3 

esc 4/15 

08/15 

- 


* If a single byte representation of SS2 is required in 7 bits, it should be coded as 1/9. 
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Text Font Index 

The text_f ont.index procedure allows you to select fonts from the current character set. 
The default character set has two fonts: 

• font index = 1 - A fixed-width character font. 

• font index = 2 - A variable-width character font. 

This example was created by the program text27c.c found in /usr/lib/starbase/demos. 

C Syntax 

character_height(fildes,0.04); 

text2d(fildes,0.0,0.6,"Fixed Width Text FontVDC.TEXT,FALSE); 
text2d(fildes,0.0,0.2,"Variable Width Text Font.",VDC_TEXT,FALSE); 

character_height(fildes,0.1); 

text2d(fildes,0.0,0.5,"i like to bike",VDC_TEXT,FALSE); 
text_font_index(fildes,2); 

text2d(fildes,0.0,0.1,"i like to bike",VDC_TEXT,FALSE); 

Fortran77 Syntax 

call character.height(fildes,0.04) 

rail text2d(fi1des ; 0 0.0.6,’Fixed Width Text Font.’//NULL,VDC_TEXT.FALSE) 
call text2d(fildes,0.0,0.2,’Variable Width Text Font.’//NULL,VDC.TEXT, 
c FALSE) 

call character.height(fildes,0.1) 

call text2d(fildes,0.0,0.5, ’i like to bike’//NULL,VDC.TEXT,FALSE) 
call text.font_index(fildes,2) 

call text2d(fildes,0.0,0.1,’i like to bike’//NULL,VDC.TEXT,FALSE) 
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Pascal Syntax 

character_height(fildes,0.04); 

text2d(fildes,0.0,0.6,’Fixed Width Text FontVDC_TEXT,FALSE); 
text2d(fildes,0.0,0.2,’Variable Width Text Font.’,VDC_TEXT,FALSE); 

character_height(fildes,0.1); 

text2d(fildes,0.0,0.5,’i like to bike’,VDC_TEXT,FALSE); 
text_font_index(fildes,2); 

text2d(fildes,0.0,0.1,'i like to bike’,VDC_TEXT,FALSE); 


r 


Fixed Width Text Font. 


l like to bike 


Variable Width Text Font. 

l like to bike 


v_ 

Figure 2-28. Character Fonts (text26c.c_) 
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Text Color 

Text color is selected in the same manner as the fill color, perimeter color and marker 
colors are selected. 

See the section Color in this manual for further information on Starbase color. 
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Notes 
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Starbase Color Graphics 

Introduction 

The following discussion of color graphics applies to those color graphic devices supported 
by the Starbase system. Not all devices support all color capabilities described in this 
chapter. See the Starbase Device Drivers Library for detailed information concerning 
color support for a specific device. 

The following procedures are involved with color: 

• Background Color 

• background.color - sets the background color by specifying the red, green 
and blue components of the desired color. The clear_view_surface procedure 
paints the background. 

• background_color_index - sets the background color by specifying the color 
map index of the desired color. The clear_view_surface procedure paints the 
background. 

• clear_view_surface - removes all graphic elements and paints the area specified 
by the clear.control procedure in the color specified by the background_color 
procedure. 

• clear.control - specifies the area of the view surface to be cleared by the 
clear_view_surface procedure. The view surface may be one of the following: 

• CLEAR_VDC_EXTENT - clear the rectangle defined by the vdc_extent 
procedure. 

• CLEAR_CLIP_RECTANGLE - clear the rectangle defined by the 
clip.rectangle procedure. 

• CLEAR_DISPLAY_SURFACE - clear the rectangle defined by the 
set_pl_p2 procedure. This is the default. 

• clip.rectangle - defines the current clip rectangle. Graphic elements that ex¬ 
tend beyond this rectangle are automatically clipped when dipping is enabled 
(see clipjndicator). 

• set_pl_p2 - specifies the bounds (pi and p2) of the device. 
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• The Color Table 

• define_color_table - defines the red, green and blue components of the color 
table entries. 

• inquire_sizes - returns the devices physical limits, resolution, (pi, p2), and 
color map size. 

• Line Color 

• draw2d, draw3d and dedraw - draws lines between coordinate points. Line 
color is defined by the line_color procedures. 

• line_color - selects the color of lines drawn by Starbase by specifying the lines 
red, green and blue components. 

• line_color_index - selects the color of lines drawn by Starbase by specifying 
the the index into the color map. 

• perimeter.color - selects the color of perimeters drawn by Starbase by speci¬ 
fying the lines red, green and blue components. 

• perimeter_color_index - selects the color of perimeters drawn by Starbase by 
specifying the the index into the color map. 

• polyline - draws line segments defined by a list of points. The color of the 
lines is defined by the line_color procedures. 

• Fill Color 

• filLcolor - selects the red, green and blue components of the fill color. The 
fill color is used to fill polygons and rectangles. 

• filLcolor_index - selects the fill color by an index into the color map. The fill 
color is used to fill polygons and rectangles. 

• filLdither - selects the number of colors to be searched for and placed in the 
dither cell. Only 1, 2, 4, 8 and 16 colors are allowed. Devices may limit 
the number of options implemented for this parameter depending on device 
capabilities. 

• rectangle - draws rectangles. Default rectangles are filled and without perime¬ 
ters. 

• polygon - draws polygons. Default polygons are filled and without perimeters. 
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Marker Color 

• marker.color - selects the color of markers drawn by Starbase by specifying 
the lines red, green and blue components. 

• marker_color_index - selects the color of markers drawn by Starbase by spec¬ 
ifying the the index into the color map. 

• polymarker - draws markers at designated locations. The color of the markers 
if defined by the marker.color procedures. 

• Text Color 

• text 2d, text 3d, detext and append_text - draw textual characters. The color 
of the characters is defined by the text.color procedures. 

• text_color - selects the color of text drawn by Starbase by specifying the lines 
red, green and blue components. 

• text_color_index - selects the color of text drawn by Starbase by specifying 
the the index into the color map. 
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Color Generation 

An Overview 

All color is device dependent. Each device has its own color capabilities and color map. 

Each display pixel is mapped into an address in a section of the computer’s internal 
memory called the frame buffer. Each frame buffer address contains a number that is an 
index into the device’s color map. In the following example, the example frame buffer 
entry contains the color map index value 3. 

The address of the color map is stored as a binary number. For example, the addresses 
of the HP 2627 Color Map contains 8 bits. Each bit position can be referred to as a 
color plane for that device. All of the least significant bits are plane 0, all of the most 
significant bits (for this device) are plane 7. Starbase allows you to disable color planes, 
i.e. ignoring any l’s in that column of bits. This limits the possible colors that can be 
displayed. 

The color map can be thought of as a 8 by n array. The three row entries define a binary 
value that produce a color intensity from the color generation hardware. 

The color hardware generation hardware controls the beam of light sent to the display. 

The dot on the display is the pixel identified by the frame buffer. 
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Figure 3-1. The Color Generation Process 
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The Frame Buffer 

Starbase supports bit-mapped color graphics. An area in memory called a frame buffer 
provides a memory location for each pixel on the device’s display. Each location contains 
an integer which is an index into the device’s color map and thus defines the color for 
that pixel. The color description used in the frame buffer is indirect Thus, the value in 
the frame buffer does not say “use color 12”, but rather “use the color described by the 
color map at index number 12”. 

Initially, all locations in the buffer contain the value of the currently defined background 
color. When you draw a line on the screen, what really happens is the values for the 
correct frame buffer locations are changed to the currently defined line color. 

Color Categories 

At any given time, the values written to the frame buffer fall into six categories: 

• Background Color - Whenever clear_view_surface is executed, all pixel locations 
in the frame buffer area to be cleared are set to the background color defined by 
the background_color procedure. The default background color is color table index 
0 (zero). 

• Line Color - Line color is selected with either line_color or line_color_index. Lines 
are created with the polyline, draw2d, draw3d and dedraw procedures. The default 
line color is color table index 1 (one). 

• Perimeter Color - Perimeter color is selected with either perimeter_color or perime- 
ter_color_index. Polygons may be created with or without perimeters, depending 
on the interior_style procedure. Perimeters may be drawn with the polygon, 
rectangle, and partial_polygon procedures. The default perimeter color is color 
table index 1 (one). 

• Text Color - Text color is selected with either text.color or text_color_index. Text 
is drawn using the append_text, text2d and text3d procedures. The default text 
color is color table index 1 (one). 

• Fill Color - Fill color is selected with either f ill.color or f ill_color_index. Poly¬ 
gons may be filled or not filled depending upon the interior.style procedure. 
Polygons are created using the polygon, rectangle, and partial.polygon proce¬ 
dures. The default fill color is color table index 1 (one). 

• Marker Color - Marker color is selected with marker_color or marker_color_index. 
Markers are drawn using the polymarker procedure. The default marker color is 
color table index 1 (one). 
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All of the color control statements listed above are referred to as modal attributes. This 
means that the value established by one of the statements stays in effect for that class 
of objects until altered by another statement. 


The Color Map 

Color Planes 

The index into the color map is stored as binary values. Each device uses a specific num¬ 
ber of binary bits to identify the colors available. For example, the HP 98700 supports 
256 entries in the color map, thus needing 8 bits to identify each entry in the map. The 
HP 2627 supports 8 and requires 3 bits while the HP 2623 supports 2 colors and only one 
bit. The bit locations for the index values in the color map are called the color planes of 
the device. The colors available can be limited by enabling and disabling these planes. 

Color Map Entries 

The color map contains a complete description of the colors available for the device. Each 
color map index identifies three entries, one for each of the primary colors - Red, Green 
and Blue. The number of colors possible in a device is found by raising the number 2 to 
the power found by adding up the total number of bits used to specify the three colors. 
For the HP 98700, this value is over 16 million possible colors, of which, 256 can be active 
at a time. 

Color Generation Hardware 

The binary bits stored in the three segments of a color map entry form a pattern that, 
when applied to the Analog-to-Digital Converters in the raster device, produces a specific 
voltage level which causes that color to be of a specific intensity. The sum of the three 
intensities is the color seen on the display. 
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Selecting a Color 

There are two ways to select a color: 

• Specify the index into the color map. This is the fastest way to access a color. For 
example: 

background_color_index(fildes,2); 

• Specify the red, blue and green components of the color. Starbase will take your 
specification and will search the color table for the closest match. The index for 
that color is then used. This method is slower than the first due to the search 
time, however, when a specific color is wanted, this gives you the closest match. 
For example: 

background_color(fildes,0.20,1.00,0.50); 


Shell Scripts 

The following shell scripts can be used to compile and execute the example programs 
described in this section. The scripts work with both the Bourne Shell and the C Shell 
(the C Shell calls the Bourne shell automatically). 

The *“-1” option is used to reduce typing. This compiler option prepends /usr/lib/lib 
to the file name and appends .a to the file name. This completes the path name to the 
correct file. For example: 

. . . -lddhpgl 

is processed as if it were 

... /usr/lib/libddhpgl.a 
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A Script for C Programs 

To following script will compile and run a C program, linking in the drivers for the HP- 
GL and HP 2627 devices and the required starbase libraries sbl and sb2. This script also 
allows you to easily link in other device drivers. 

PR0G=$1 

shift 

cc -o $PR0G $PR0G.c $* -lddhpgl -ldd2627 -lsbl -lsb2 
$PR0G 

This script is available in /usr/lib/starbase/demos as the executable file CC. 

To compile and execute the example program progl. c just type in: 

CC progl 

To execute the same program again, just type in: 

progl 

To link in the device driver for the HP 98700, just recompile with: 

CC progl -ldd98700 

A Script for Fortran77 Programs 

To following script will compile a Fortran77 program, linking in the drivers for the HP- 
GL and HP 2627 devices and the required starbase libraries sbl and sb2. This script also 
allows you to easily link in other device drivers. 

PRQG=$1 

shift 

fc -o $PR0G $PR0G.f $* -lddhpgl -ldd2627 -lsbl -lsb2 
$PR0G 

This script is available in /usr/lib/starbase/demos as the executable file FC. 

To compile and execute the example program progl.f just type in: 

FC progl 

To execute the same program again, just type in: 

progl 

To link in the device driver for the HP 98700, just recompile with: 

FC progl -ldd98700 
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A Script for Pascal Programs 

To following script will compile a Pascal program, linking in the drivers for the HP-GL 
and HP 2627 devices and the required starbase libraries sbl and sb2. This script also 
allows you to easily link in other device drivers. 

PR0G=$1 

shift 

pc -o $PR0G $PR0G.p $* -lddhpgl -ldd2627 -lsbl -lsb2 
$PR0G 

This script is available in /usr/lib/starbase/demos as the executable file PC. 

To compile and execute the example program progl.p just type in: 

PC progl 

To execute the same program again, just type in: 

progl 

To link in the device driver for the HP 98700, just recompile with: 

PC progl -ldd98700 


166 Starbase Color Graphics 



Skeleton Programs 

The following programs provide the various include files, the procedures that open and 
close the graphics devices and the other components needed to make working Starbase 
programs. The appropriate procedures are added and the result will compile and execute. 

A Template Program for C 

#include <starbase.c.h> 

main(argc,argv) 

int argc; char *argv[]; 

int fildes; 

if (argc > 2) f ildes=gopen(argv [1] , OUTDEV, argv [2] ,N0_INIT) 
else fildes=gopen("/dev/tty ",OUTDEV,"hp262x",INIT); 
if (fildes == -1) exit(-l); 


make_picture_current(fildes); 
gclose(fildes); 

> 

A Template Program for Fortran77 

include ’/usr/include/starb^se fl h’ 

program chart 

character NULL 

parameter(NULL = char(O)) 

include ’/usr/include/starbase.f2.h’ 

integer*4 fildes 
integer*4 status 

fildes = gopen(*/dev/tty *//NULL, OUTDEV, 5 hp262x’//NULL, INIT) 
if (fildes .eq. -1) stop 

status = gclose(fildes) 
end 
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A Template Program for Pascal 

program main(input,output); 

$include ’/usr/include/starbase.pi.h’$ 
var 

fildes, status : integer; 

$include */usr/include/starbase.p2.h’$ 
procedure exit(result: integer); external; 

begin {main} 

fildes:=gopen(’/dev/tty *,OUTDEV,’hp262x’,INIT); 
if fildes = -1 then exit(-l); 

status := gclose(fildes); 
end. 


Example Color Programs 

The example programs that follow will present different colors depending upon the cur¬ 
rent definition of the device’s color map. The examples were created using the color map 
for the HP 2627 Color Graphics Terminal. 

A Color Map 

The following example was used to generate the color map used by the HP 2627 Color 
Graphics Terminal. This example shows the colors of the map, and also demonstrates 
how the line, fill and text colors can be selected. 

int fildes, color=0; 
float y, r[1] [3]; 
char c [80]; 
char x [80]; 

static char *name[] = { 

"Black", 

"White", 

"Red", 

"Yellow", 

"Green", 

"Cyan", 

"Blue", 

"Magenta"}; 

mapping_mode(fildes.TRUE); 
character_height(fildes,0.06); 
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character_width(fildes,0.015); 
interior_style(fildes,INT.SOLID,TRUE); 

text.alignment(fildes,TA.NORMAL.HORIZONTAL,TA.HALF,0.0,0.0); 

for (y=0.0; y<=0.8; y+=0.1) { 

fill_color_index(fildes,color); 
rectangle(f ildes ,0.60^,0.73^+0.08) ; 
inquire_color_table(fildes,color,1,r); 
text2d(fildes,0.75,y+0.02,name[color],VDC_TEXT,FALSE); 
sprintf (x, "Red = 7,3.2f Green = 7,3.2f Blue = 7.3.2f", 
r [0] [0] ,r [0] [1] ,r [0] [2]); 
sprintf (c, "Pen 7.d", color++); 
text2d(fildes,0.0,y+0.02,x,VDC.TEXT,FALSE); 
text2d(fildes,0.63,y+0.02,c,VDC.TEXT,FALSE); 

> 
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Figure 3-2. A Color Map (colorlc.c) 
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Background Color 

These procedures are device dependent and only work with those devices that have 
backgrounds. An exception is a plotter with automatic paper feed. The plotter will 
advance the paper whenever a backgroundsolor procedure is executed. 

The background area defined by the clear.control procedure is painted the color speci¬ 
fied by either the background.coior or background_coior_index procedure with each ex¬ 
ecution of the clear_view_surf ace procedure. This painting causes the entire area to be 
the color specified. 

The clear_control procedure uses the following enumerated types to define the areas to 
be painted: 

• CLEAR. VDC.EXTENT - the rectangle defined by the vdc.extent procedure. 

• CLEAR.CLIP.RECTANGLE - the rectangle defined by the clip.rectangle pro¬ 
cedure. 

• CLEAR.DISPLAY.SURFACE - clear the rectangle defined by the set_pl_p2 pro¬ 
cedure. 

The following program segment, when placed in the template for C programs produces 
three background fills. First, the default fill area, the area defined by PI and P2, is 
painted the color found at color map index 4. Next, the values of PI and P2 are changed 
with respect to the original values. Since the Virtual Device Coordinate Extent is also 
defined by PI and P2, 


background_color_index(fildes,4); 
clear_view.surface(fildes); 

set_pl_p2(fildes.FRACTIONAL,0.1,0.1,0.0,0.9,0.9,0.0); 
background_color_index(fildes,5); 
clear.control(fildes,CLEAR.VDC.EXTENT); 
clear.view.surface(fildes); 

clip.rectangle(fildes,0.3,0.7,0.3,0.7); 
backgroundsolor.index(f ildes ,6) ; 
clear.control(fildes,CLEAR.CLIP.RECTANGLE); 
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Figure 3-3. Background Color (color2c.c) 

Polyline and Polymarker Color 

The following example is used to show how polylines and markers can be drawn in 
different colors. 

int fildes,y,num_pts; 
float clist[8]; 

float ph_lim[2] [3] , res[3], pl[3], p2[3] ; 
int num.pens; 
char c [80]; 
char m[80]; 

inquire.sizes(fildes,ph_lim,res,pl,p2,&num_pens); 

vdc_extent(fildes,0.0,0.0,0.0,25.0,10.0,0.0); 
clip_rectangle(fildes,0.0,25.0,0.0,10.0); 
mapping_mode(fildes.TRUE); 

marker_orientation(fildes,0.0,1.0); 


Starbase Color Graphics 171 









marker_size(fildes,0.2,1); 
character_height(fildes,0.35); 

for (y=0; y<=8; y++)< 

line_color_index(f ildes ,y # / 0 num_pens); 
marker_color_index(f ildes, (y+l) # / 0 mim_pens); 


clist[0]=9.0; 
clist [2]=14.0 
clist[4]=19.0 
clist[6]=24.0 


clist[1]=y+0.50 
clist[3]=y+l.50 
clist [5]=y+l.50 
clist [7]=y+0.50 


marker_type(fildes,y) ; 
polyline2d(fildes,clist.4,0); 
polymarker2d(fildes,clist,4,0); 


sprintf (c , "Line Color Index # /,d", y®/ 0 num_pens) ; 
sprintf (m, "Marker Color Index # / 0 d" , (y+l) # /,num_pens) 
text2d(fildes,0.30,y+0.35,c,VDC.TEXT,FALSE); 
text2d(fildes,0.30,y+0.65,m,VDC_TEXT,FALSE); 

> 
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Figure 3-4. Polyline and Polymarker Color (color3c.c) 
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The Color Cube 

The RGB color cube describes an additive color system. In an additive color system, 
color is generated by mixing various colored light sources to produce different colors. 

The origin (0,0,0) of the RBG color cube is black. Increasing values of each of the additive 
primary colors (Red, Green and Blue) move towards white (the opposite corner of the 
cube.) The maximum value for all three colors is white. 

A diagonal of the cube connecting point (0,0,0) and point (1,1,1) represents gray shades, 
which are generated by incrementing all three colors axes equally. 

#include <starbase.c.h> 

#include <stdio.h> 

extern double sin(), cos(); 

#define scale_screen 1.125 
#define sin_30_degrees 0.5 
#define cos_30_degrees 0.866025 


main(argc,argv) 

int argc; char *argv[]; 

{ 

int fildes; 

float size, ph_lim[2] [3] , res [3] , pi [3] , p2[3]; 
float extent, s, c; 

int cmap_size, dither_size, step, r, g, b, valid; 
char ch; 

if (argc>2) fildes=gopen(argv[1],0UTDEV,argv[2],INIT); 
else fildes=gopen("/dev/tty",0UTDEV,"hp2627",INIT); 
if (fildes == -1) exit(l); 

inquire_sizes(fildes,ph_lim,res,pl,p2,&cmap_size); 

valid = FALSE; 
while (!valid) { 

printf("Enter dither size (1,2,4,8 or 16): "); 
scanf (" # / 0 d" ,&dither_size) ; 

if ((dither_size == 1) II (dither_size == 2) I I 
(dither.size == 4) I I (dither_size == 8) I I 
(dither_size == 16)) valid = TRUE; 

> 

fill.dither(fildes,dither_size); 
fflush(stdin); 
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s = sin_30_degrees; 
c = cos_30_degrees; 

extent = cmap_size * scale_screen; 
step = cmap_size/8; 

vdc_extent(fildes,-extent,-extent,0.0,extent,extent,0.0); 
clip_rectangle(fildes,-extent,extent,-extent,extent) ; 

for (g=0; g<=cmap_size; g=g+step) { 
for (r=0; r<=cmap_size; r=r+step) { 
for (b=0; b<=cmap_size; b=b+step) { 

fill_color(fildes,(float)r/cmap_size,(float)g/cmap_size, 
(float) b/cmap_size); 
polygon(fildes,step,c*r-c*b,g-s*r-s*b); 

> 

> 

> 

make_picture_current(fildes); 
gclose(fildes); 


polygon(fildes,scale,x,y) 
int fildes,scale; 
float x, y; 

{ 

float clist [14] ; 
int i; 


clist [0] = x; 

clist[l] = y + scale; 

clist [2] = x + cos_30_degrees * scale; 

clist [3] = y + sin_30_degrees * scale; 

clist[4] = x + cos_30_degrees * scale; 

clist [5] = y - sin_30_degrees * scale; 

clist [6] = x; 

clist [7] = y - scale; 

clist[8] = x - cos_30_degrees * scale; 

clist [9] = y - sin_30_degrees * scale; 

clist [10] = x - cos_30_degrees * scale; 

clist [11] = y + sin_30_degrees * scale; 

clist [12] = x; 

clist[13] = y + scale; 


polygon2d(fildes,clist,7,0); 
make_picture_current(fildes); 
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Figure 3-5. Color Cube (color4c.c) 
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Input _ 

Introduction 

The Starbase input model involves two classes of input: 

• Locator Devices - return x, y, and z coordinates. 

• Choice Devices - return a single integer value. 

A file descriptor may be associated with any number of locators and choice devices, 
depending on the nature of the physical device which it represents. The number of 
locators and number of choice devices associated with a file descriptor may be determined 
by calling inquire_input_capabilities. This call also lists the number of valuators and 
string devices, but these fields are only present for future extensions; no valuators or 
string devices are currently implemented. 



Locator Devices 

Locators return floating point numbers in Virtual Device Coordinate (VDC) values. The 
range of VDC values is determined separately for each file descriptor and may be different 
for input and output devices. The range of values may be set to convenient units by using 
the vdc .extent procedure. Usually a locator should be set to use the same units as a 
related display device. Note that the value returned from a locator is not in World 
Coordinates and therefore is not affected by the World Coordinate transform stack. 


Choice Devices 

Choice devices return an integer value, usually describing a set of buttons or keys. One 
choice device can describe an entire keyboard or set of buttons. Most button devices 
return button numbers ranging from 1 to N, (N being the number of buttons.) Keyboard 
devices return ASCII character codes for those keys with ASCII codes. A value might 
also represent the release of a button, (usually as a negative value.) Some drivers also 
provide an alternate representation of the same set of buttons. For instance, devices 
on the HP-HIL interface loop return button numbers on choice device 1, and a bit-wise 
encoding of the same buttons on choice device 2. The buttons 1 through 32 on an HP- 
HIL device are represented by the bits 2"0 through 2"31 in the choice value. For each 
button pressed, a bit is set to 1. 
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Triggering 

Most input devices feature a way to indicate that data is ready. This trigger mechanism 
is used to proceed when the computer is waiting for a response. For choice devices this 
is a often a button or key press, (or possibly the release of a button.) For locators, the 
trigger is usually a button or a switch on the pointing device. One trigger can cause 
multiple locators and choice devices on a file descriptor to indicate that data is ready. 
This trigger mechanism is used by the request and event input techniques discussed later 
in this section. A few devices have no trigger mechanism. These devices are never waited 
for. They are always read from in a non-blocking manner. 


Input Methods 

Sampling 

Sampling reads the current value of a device without waiting for any trigger action by a 
user. Repeated samples may be used to monitor a continuously changing value. 

Requests 

A request reads the value of a device the next time that a trigger indicates data is ready. 
It may be used to read one value after prompting the user to enter data. 

Requests wait for a trigger on an input device, then return the value of the device at the 
trigger time. A program may either begin a request and proceed to other activities, or 
begin a request and wait for it to complete. Since requests take only one data value they 
are well suited to reading a single input after prompting for data. They are not suitable 
for capturing many closely spaced triggers, because triggers may be missed between the 
completion of one request and the start of another. Requests can be started on multiple 
devices, but each device must be tested separately to determine when a request has 
completed. 
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Events 

The event mechanism reads a device whenever a trigger occurs. The data from a device, 
(or several devices,) is placed into a first-in-first-out queue for later retrieval. Events 
can be used in order to be certain that all trigger actions are remembered even if an 
application program is busy when the triggers occur. 

Events use a single queue to save away the values from input devices whenever they are 
triggered. This allows an application to monitor several input devices at the same time. 
It also guarantees that triggers will not be missed. Each input device has a daemon 
process that is started whenever: 

• Events are enabled for that device. 

• Tracking is enabled for that device. 

While requests need to be restarted after completing, events remain enabled until they 
are explicitly turned off, or the device is closed. This makes event queuing well suited 
to tasks where no data should be missed, such as reading text from a keyboard. On the 
other hand, events are not convenient if data is only required as a response to a prompt. 
The program below uses events to read all locator and choice triggers from one device. 
It also uses tracking to follow the locator on a display. 

Tracking 

Tracking is the feedback from a locator device to a display Hpvic.e. An echo position 
will follow the value of locator device without any need for continuous monitoring by an 
application program. 

Tracking causes a separate process to constantly follow the value of a locator. This value 
is used to update the position of an echo on a display device. Each input device may 
track one of it’s locators to the first echo of one display. If an input device features more 
than one locator, then only one of the locators on the device can be tracked at one time. 
If an output device displays multiple simultaneous cursors, then the tracking activity will 
affect the first of these cursors. 

There is substantial overhead involved with the start of tracking, so it is best to avoid 
frequently turning tracking on and off. Since tracking always uses the current echo type, 
setting the echo type to no echo, (0), will stop visual feedback without stopping the 
tracking activity. 
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Sampling 

The procedures sample_choice and sample_locator return the current value of a choice or 
locator device. The device is specified by a file descriptor and ordinal. The call returns 
a flag, valid, which indicates when the device was unable to return a value. 

Valid may be FALSE because: 

• the device does not exist 

• there was a hardware failure 

• the device was in a bad state for sampling. 

Some devices cannot be sampled while waiting for a trigger. Such a limitation is indicated 
by the sample_while_request flag from the inquire_input_capabilities routine. Sample 
for a choice device may have different meanings for different devices. For some devices, 
sample will only return the number of the last button pressed. For other devices sample 
can return the up/down state of all buttons at the current time. Because of these 
differences in device capabilities, sample.choice is not as device independent as other 
input calls. 
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Example 1 

The program below uses a request and repeated sample calls to enter a data point. 

#include <starbase.c.h> 
main() 

{ 

int locator, display, valid, ready; 
float x, y, z; 

locator = gopen("/dev/locator", INDEV, "hp-hil", INIT); 
if (locator == -1) exit(l); 

display = gopen("/dev/crt", OUTDEV, "hp98700", INIT); 
if (display =-- -1) { 
locator = gclose(locator); 
exit(1); 

> 

sample_locator(locator, 1, fevalid, &x, &y, &z); 
echo_type(display, 1, 1, &x, &y, <fez); 
initiate_request(locator, LOCATOR, 1, fevalid); 
do { 

sample_locator(locator, 1, &valid, &x, &y, &z); 
echo_update(display, 1, x, y, z); 

inquire_request_status(locator, LOCATOR, 1, feready); 

> while (!ready); 

request.locator(locator ; 1. 1.0. &x, &v, &z); 

echo.type(display, 1, 0, x, y, z); 

printf ("7,f , # /,f , °/ 0 f \n" , x, y, z) ; 

locator = gclose(locator); 

display = gclose(display); 

> 
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Example 2 

The next program uses events and tracking to read 20 values from both a locator and a 
choice device. 

#include <starbase.c.h> 
mainO 
{ 

int locator, display; 
int valid, class; 

printf("Demonstration of events.\n"); 

locator=gopen("/dev/locator M ,INDEV,"hp-hil",INIT); 
if (locator == -1) exit(l); 

display = gopen("/dev/crt",OUTDEV,"hp98700",INIT); 
if (display == -1) { 

locator = gclose(locator); 
exit(l); 

> 

clear_view_surface(display); 
enable_events(locator.LOCATOR,1); 
enable_events(locator,CHOICE,1); 

track(locator, display, 1); 

count = 0; 
do { 

await_event(-1,2.0,&valid,&class); 
if (valid) { 

count = count + 1; 

printf ("await_event- (valid) class: # / 0 d\n", class); 
switch (class) { 
case LOCATOR: 

check_locator(display); 
break; 
case CHOICE: 

check_choice() ; 
break; 

> 

> 

else 

printf("await_event- (not valid)\n"); 

> while (count < 20); 

disable_events(locator,ALL,1); 
track_off(locator); 
gclose(display); 
gclose(locator); 
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exit(0); 

> 


check_locator(display) 
int display; 

i 

int valid, fildes, ordinal, status, message_link; 
floatx=0.5, y=0.5, z=0.0; 


valid = !read_locator_event(-1,&fildes,&ordinal,&x,&y,&z,&status, 
&message_link); 

printf("Locator:\n"); 

printf ("valid: °/,d .fildes : °/,d, ordinal: °/ 0 d, x: °/»f , y: °/,f , z :°/ 0 f \n" , valid, 
fildes,ordinal,x,y,z); 
printf("status: "); 
switch (status) { 

case EMPTY_N0_0VERFL0W: printf("empty, no overflow\n"); break; 
case N0T_EMPTY_N0_0VERFL0W:printf("not empty, nooverflow\n"); 
break; 

case EMPTY_0VERFL0W: printf("empty, overflow\n"); break; 

case N0T_EMPTY_0VERFL0W:printf("not empty, overflow\n");break; 

> 

printf("message_link: "); 
switch (message_link) { 

case SINGLE_EVENT: printf("single event\n"); break; 

case SIMULTANEOUS_EVENT_FOLLOWS:printf("simultaneous event 

f oliuwt>\n !! ) , 


if (valid) { 

move2d(display, x - 0.01, y - 0.01) 

draw2d(display, x + 0.01, y - 0.01) 

draw2d(display, x + 0.01, y + 0.01) 

draw2d(display, x - 0.01, y + 0.01) 

draw2d(display, x - 0.01, y - 0.01) 

make_picture_current(display); 
if (x < 0.1 && y < 0.1) 

> 


> 


check.choice() 

{ 

int valid, fildes, ordinal, value, status, message_link; 

valid=!read_choice_event(-1,&fildes,&ordinal,&value,&status, 
&message_link); 
printf("Choice:\n"); 

printf ("Choice : \nvalid: 7«d .fildes : 7«d, ordinal: 7«d, value : 7od\n" , 
valid.fildes,ordinal,value); 
printf("status: "); 
switch (status) { 
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case EMPTY_NO_OVERFLOW: printf("empty, no overflow\n"); break; 
case NOT_EMPTY_NO_OVERFLOW:printf("not empty, no overflow\n"); 
break; 

case EMPTY_0VERFL0W: printf("empty, overflow\n"); break; 
case N0T_EMPTY_0VERFL0W: printf("not empty, overflow\n"); 
break; 

> 


printf("message_link: "); 
switch (message_link) { 

case SINGLE_EVENT: printf("single event\n"); break; 

case SIMULTANEOUS_EVENT_FOLLOWS: printf("simultaneous event 

follows\n"); 


> 


> 
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Modeling and Viewing 


Introduction 

The viewing transformations that occur in the starbase graphics library are outlined in 
the diagram below. 



DEVICE COORDINATES 
FROM INPUT DEVICE 


DEVICE COORDINATE VALUES 
TO OUTPUT DEVICE 


Figure 4-1. Transformation Diagram 

Graphics transformations are commonly explained in terms of a modeling transformation 
which moves objects/subobjects in the user’s coordinate system followed by a viewing 
transformation which determines what subset of the users coordinate system is visible, 
and a normalized device coordinate transformation which scales to the device’s native 
coordinate system. Starbase combines these three logical steps into one actual transfor¬ 
mation, so that there is only one current transformation. 
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There are three coordinate systems that are of primary interest: 

• Device Coordinates (DC) 

• Virtual Device Coordinates (VDC) 

• World Coordinates (WC) 

Utilities that convert between these coordinate systems make it possible for the user to 
work easily in any system needed. 


Two-Dimensional Viewing 

Two-dimensional viewing is best explained with a simple windowing transformation. 
A window can be specified in an arbitrary coordinate system (the World Coordinate 
System) defined by the application program. These units can be any units that are 
convenient for the user’s program; i.e., inches, feet, millimetres, years, dollars, etc. 

The portion of the graphical data which is within this window will be visible on the screen 
(physical display surface) within the current viewport (subset of screen). The manner in 
which this happens is that the full extent of the window maps to the full extent of the 
viewport. 

Any portions of the graphical data which lie outside of the window are clipped (discarded 
from the picture). 

Using starbase, there is more than one way to do windowing. The simplest is to use 
the vdc_extent procedure to scale the range of virtual device coordinates to be that 
of the window. The viewport position and size can be changed with the set_pl_p2, 
viewport.justif ication, and mapping.mode procedures. 
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Example 1: 

In the following example, a viewport which fills the entire HP 98710 display is set to 
receive data with the X-axis defined in years from 1980 thru 1985 and the Y-axis defined 
in dollars from $0.00 thru $100.00. 

gopen(fildes,"/dev/crt",0UTDEV,"hp98710",INIT); 

vdc.extent(fildes,1980.0,0.0,0.0,1985.0,100.0,0.0); 
clip_rectangle(fildes,1980.0,1985.0,0.0,100.0); 
mapping_mode(fildes,ISOTROPIC); 

set_pl_p2(fildes,FRACTIONAL,0.0,0.0,0.0,1.0,1.0,1.0); 

Example 2: 

In this second example, a window is created in the upper-right quarter of the display. 
gopen(fildes."/dev/crt".OUTDEV,"hp98710",INIT); 

/* Set up window. X and Y axes are both inches. */ 

vdc_extent(fildes,500.0,900.0,0.0,200.0,400.0); 
clip_rectangle(fildes,500.0,900.0,200.0,400.0); 

/* Viewport is restricted to upper right quarter of screen. */ 

mapping_mode(fildes,ISOTROPIC); 

set_pl_p2(fildes.FRACTIONAL,0.5,0.5,0.0,1.0,1.0,0.0); 

/* Viewport is centered in x and y within pl_p2 area to */ 

/* maintain isotropic units. */ 

viewport.justification(fildes,0.5,0.5); 

A more elaborate way of doing windowing is to set up vdc.extent to a fixed normalized 
device coordinate range and window changes can be implemented using a 2-dimensional 
transformation matrix. The mapping and positioning defined by the above equations 
are simply the scaling and translations terms of a 2-dimensional matrix. This second 
method has the advantage that the window can also be made to rotate within the user’s 
arbitrary coordinate system by using the rotation components of the matrix. The view¬ 
port can then be changed by just changing the clip.rectangle and appropriate scaling 
and translation terms of the matrix. 
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Using The Transformation Matrix Stack 

Starbase has a transformation stack that can be used to concatenate and/or stack graph¬ 
ics viewing/modeling matrix operations. This feature is useful for composing a viewing 
matrix, instancing objects/subobjects, and temporarily changing the current transfor¬ 
mation and returning to the previous state. It can also be used as general-purpose 4x4 
transformation engine for such things as bspline curve generation. 

The top of the matrix stack is the current transformation matrix, through which all 
output primitives are transformed. Conceptually, and in the actual implementation, 
the vdc-to-device coordinate transformation is a transformation matrix also. It can be 
thought of as the matrix at the bottom of the matrix stack which can never be popped or 
replaced using the matrix operations. It can be changed by using the vdc operations spec¬ 
ified in the manual (vdc_extent, set_pl_p2, mapping.mode, and viewport justification). 
The vdc-to-device matrix is the current transformation matrix immediately after a gopen 
since the matrix stack is empty. 

The push and replace matrix operations are always concatenated with the current vdc- 
to-device matrix. This provides device independence when using the matrix stack. The 
matrix concatenation operations will concatenate with the current transformation ma¬ 
trix. If the matrix stack is empty, this concatenation is performed with the vdc-to-device 
matrix. 

The post-concatenation option on matrix concatenation operations is NOT recommended 
for the novice user. The results are device dependent because the matrix is post- 
concatenated after the vdc-to-device transformation. 

The push, vdc .matrix is a convenient and efficient means of getting the vdc-to-device 
matrix onto the top of the matrix stack. Changes to the vdc-to-device matrix DO NOT 
affect any matrices on the stack that were concatenated with the vdc-to-device matrix 
OR any matrices on the stack that were put there using push.vdc.matrix. It is highly 
recommended to flush the matrix stack before changing the vdc-to-device matrix. 

Now that the matrix stack usage has been reviewed, the second method of doing a 
2-dimensional windowing transformation can be demonstrated. 
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Example 3 


/* Initialize the range of virtual device. */ 

gopen(fildes,"/dev/crt",OUTDEV,"hp98710",INIT); 
vdc_extent(fildes,0.0,0.0,0.0,1.0,1.0,1.0); 
mapping_mode(fildes,ISOTROPIC); 
push_vdc_matrix(fildes) ; 

/* Each time the window is changed, the following must be done. */ 

clip_rectangle(fildes,Vxl,Vxr,Vyb,Vyt); 

Sx = (Vxr - Vxl)/(Wxr - Wxl); 

Sy = (Vyt - Vyb)/(Wyt - Wyb); 
winxform[0] [0] = Sx; 
winxform[0] [1] =0; 
winxform[l][0] = 0; 
winxform[l][1] = Sy; 
winxform[2] [0] = Sx*Wxl + Vxl; 
winxform[2][1] = Sy*Wyb + Vyb; 
replace_matrix2d(fildes,winxform); 

In the above example, if Wxl=400, Wxr=900, Wyb=300, Wyt=700, and Vxl=0.5, 
Vxr=1.0, Vyb=0.5, Vyt=1.0, then the range of window coordinates 400 to 900 in x 
and 300 to 700 will map to the upper left quarter of the screen. 

The other operation besides windowing that the transformation stack is useful for is mod¬ 
eling transformations. By setting up the viewing operation first and then concatenating 
modeling matrices onto the top of the matrix stack, objects can be moved or “instanced” 
in different positions in the user’s coordinate system. Also, subobjects can be made a 
part of other objects by making the subobject’s position and orientation relative to the 
object’s position and orientation. This is done by concatenating the subobject’s trans¬ 
formation onto that of the object before drawing the subobject. Then the subobject’s 
transformation is popped off the stack at completion of subobject. 

Devices that implement matrix stacks in hardware have a limit to the number of matrices 
that can be on the matrix stack at any one time. 
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Three-Dimensional Viewing 

Before doing any three-dimensional primitives, the device must be “gopened” with the 
THREE.D mode. 

Three-dimensional viewing is best explained with a simple camera model. This cam¬ 
era can be positioned in an arbitrary 3D coordinate system defined by the application 
program. These units can be any units that are convenient for the user’s program; i.e., 
inches, feet, millimetres, years, dollars, etc. The portion of the graphical data which is 
within the camera view will be visible on the screen within the current viewport. The 
camera model discussed here is implemented in the file /usr/lib/starbase/demos/sb.3d.c 
and used in several of the demos in the directory /usr/lib/starbase/demos. The param¬ 
eters which will be used on the camera routine will be position of the camera (cx,cy,cz) 
and position that the camera is pointed at, or the reference point (rx,ry,rz). The trans¬ 
formation matrix that accomplishes this camera operation is the concatenation of several 
matrices. First a translation to the camera position, then a rotation to rotate XYZ into 
the eye coordinate system, and finally a perspective transformation. The actual me¬ 
chanics of the individual matrix operations can be investigated in depth by reviewing a 
graphics text book. The camera transformation is accomplished using starbase by first 
pushing the perspective matrix onto the stack (matrix operations occur in reverse order.) 
Since the intermediate results of the three matrix steps outlined above are of no interest, 
the rotation is pre-concatenated with the perspective and then replaces the perspective 
matrix on the top of stack. Similarly, the translation matrix is pre-concatenated with 
the top of the stack and the result replaces the top of the matrix stack. 

Once the camera is positioned, the matrix stack only has one matrix in it, then the 
remainder of the matrix stack can be used for the modeling transformations needed to 
move objects around in the world coordinate system. For example, suppose we have a 
data base that describes a jet, as in the fighter demo (fighter.c). The camera can be 
positioned only once and the jet itself can be rotated with modeling transformations. In 
the fighter demo, it is not obvious whether the camera or the fighter is being rotated. 
If a background of trees or something similar was drawn in a fixed position in the users 
coordinate system, it would be more obvious that the jet was moving, not the camera. 

The tractor demo (trac.c) is an even better example of the use of both viewing and 
modeling transformations. The camera position can be changed using the input device 
while the tractor itself moves down the bumpy road with modeling transformations. The 
tractor body moves down the road while each of the wheels is just another instance of the 
“wheel” database with different positions and rotations. The road remains in place the 
entire time. The camera is always pointed at the middle of the tractor for convenience. 
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Multiple Active Devices 

When using more than one starbase device at a time, it is possible to establish a different 
viewing operation on each device since all state is maintained per device. Although this 
may prove useful in some cases, it is not the general usage. In general, it is advisable to 
set up the vdc to be equal on the two devices. That way input values can be read from 
the input device in vdcs and convejted to world coordinates using the output device’s 
matrix stack, using vdc_to_wc. Thus only the output device will need to maintain a 
matrix stack. 

Since distortion on an input device is not a problem unless digitizing an object, it is 
probably best to always set the mapping mode to isotropic with 
mapping.mode(fildes,ISOTROPIC); 

for input devices. This will allow use of the entire device range. 
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Manual Comment Sheet Instruction 

If you have any comments or questions regarding this manual, write them on the enclosed comment 
sheets and place them in the mail. Include page numbers with your comments wherever possible. 

If there is a revision number, (found on the Printing History page), include it on the comment sheet. 
Also include a return address so that we can respond as soon as possible. 

The sheets are designed to be folded into thirds along the dotted lines and taped closed Do not use 
staples. 


Thank you for your time and interest. 
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